cited-cli 0.5.1__tar.gz → 0.6.0__tar.gz

{cited_cli-0.5.1 → cited_cli-0.6.0}/CLAUDE.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 Monorepo for the [Cited](https://youcited.com) GEO platform tooling. Contains three Python packages:
 
 - **`cited-core`** (`packages/core/`) — Shared library: API client, auth, config, endpoints, errors. No CLI or MCP dependencies.
-- **`cited-mcp`** (`packages/mcp/`) — Standalone MCP server with 47 tools. Depends on `cited-core` + `mcp` SDK. Installable via `pip install cited-mcp` or `uvx cited-mcp`.
+- **`cited-mcp`** (`packages/mcp/`) — Standalone MCP server with 88 tools. Depends on `cited-core` + `mcp` SDK. Installable via `pip install cited-mcp` or `uvx cited-mcp`.
 - **`cited-cli`** (root `src/cited_cli/`) — Typer + Rich CLI. Depends on `cited-core` + `typer` + `rich`. Optional dep on `cited-mcp` for `cited mcp serve`.
 
 Also contains `cited-plugins/` — a Claude Code plugin (skills, commands, agents) that references the MCP server via `uvx cited-mcp`.
@@ -48,18 +48,21 @@ cited mcp serve              # Via CLI (requires cited-cli[mcp])
 **`cited-core`** (`packages/core/src/cited_core/`) — Zero CLI/MCP dependencies:
 - `api/client.py` — `CitedClient` (httpx sync)
 - `api/endpoints.py` — API endpoint path constants
-- `auth/store.py` — `TokenStore` (keyring + file fallback)
+- `auth/store.py` — `TokenStore` (keyring + file fallback); also stores per-env agent keys (`agent_key:<env>`)
+- `auth/credentials.py` — `resolve_agent_api_key()` (env var → config → saved key)
 - `auth/oauth_server.py` — Temporary localhost OAuth callback server
 - `config/manager.py` — `ConfigManager` (TOML config)
 - `config/constants.py` — `ENVIRONMENTS`, `CONFIG_DIR`, `VALID_INDUSTRIES`, etc.
 - `errors.py` — `CitedAPIError`, `ExitCode`, `exit_code_for_status()`
 
-**`cited-mcp`** (`packages/mcp/src/cited_mcp/`) — MCP server + 47 tools:
+**`cited-mcp`** (`packages/mcp/src/cited_mcp/`) — MCP server + 88 tools:
 - `server.py` — `FastMCP` instance, lifespan, `run_server()`
-- `tools/` — auth, business, audit, recommend, solution, job tool modules
-- `plan_gating.py` — Per-plan tool access control (growth/scale/pro tiers)
+- `tools/` — auth, business, audit, recommend, solution, job, docs (public docs search), billing (credits), agent_keys (agent signup + per-user keys) tool modules
+- No plans or tiers: every tool is available to every account. Paid work is charged in credits by the backend, which returns HTTP 402 (`insufficient_credits` / `purchase_required`) or 403 `claim_required`; `tools/_helpers.py::_api_error_response` flattens the `detail` object (`error_type`, `credits_needed`, `balance`, `buy_url`, `claim_url`, `payment_required`) and adds a hint
+- `log_tool_call` copies the API's `X-Cited-Notice` response header into every tool result as a top-level `notice` (via a ContextVar in `cited_core.api.client`)
 - `auth_provider.py` — OAuth provider with stateless JWT tokens and user JWT expiry detection
-- Supports `CITED_TOKEN` and `CITED_AGENT_API_KEY` env vars
+- Supports `CITED_TOKEN` and `CITED_AGENT_API_KEY` env vars; the agent key can also come from the `agent_api_key` config value or the key `agent_signup` saved (`TokenStore.get_agent_key(env)`), resolved by `cited_core.auth.credentials.resolve_agent_api_key`
+- The remote server also accepts an agent key (`cak_...`) as the Bearer token and forwards it as `X-Agent-API-Key`
 - Includes browser OAuth `login` tool for Claude Desktop users
 - Remote server (`remote.py`) runs stateless HTTP with Fargate Spot auto-scaling
 
@@ -98,11 +101,11 @@ print_result(data, out, human_formatter=lambda d, c: render_kv("Title", d, c))
 - **Token storage:** Per-environment via OS keychain (`keyring`) with a file fallback (`~/.cited/credentials.json`). The token is sent back to the API as a cookie, not a Bearer header.
 - **TTY detection:** `commands/auth.py` uses `_is_interactive()` (wrapping `sys.stdin.isatty()`) for all TTY checks — tests monkeypatch this helper.
 
-**Agent API auth** uses a separate path: `X-Agent-API-Key` header, configured via `cited config set agent_api_key` or `CITED_AGENT_API_KEY` env var.
+**Agent keys:** per-user agent keys (`cak_...`) authenticate every request via the `X-Agent-API-Key` header. Sources, in order: `CITED_AGENT_API_KEY`, `cited config set agent_api_key`, then the key saved by `cited agent signup` / the `agent_signup` tool. A login session token takes precedence: `CitedClient` only sends the key when it has no token. CLI commands build their client with `utils/client.py::get_authed_client()`, which uses the token or falls back to the agent key.
 
 **Adding a new command group:**
 1. Create `src/cited_cli/commands/<name>.py` with a `typer.Typer()` instance
-2. Add endpoint paths to `src/cited_cli/api/endpoints.py`
+2. Add endpoint paths to `packages/core/src/cited_core/api/endpoints.py`
 3. Register in `app.py` with `app.add_typer(..., name="<name>")`
 
 **Adding a nested command group (sub-subcommands):**
@@ -123,13 +126,13 @@ This gives `cited audit template list|get|create|update|delete` while `cited aud
 When adding a new feature:
 1. Add the CLI command in `src/cited_cli/commands/`
 2. Add the MCP tool in `packages/mcp/src/cited_mcp/tools/`
-3. Add the tool to `plan_gating.py` (in the appropriate tier set)
-4. Update the `_CLI_TO_MCP` mapping in `tests/test_feature_parity.py`
-5. If the feature is intentionally one-interface-only, add it to `CLI_ONLY` or `MCP_ONLY` with a comment explaining why
+3. Update the `_CLI_TO_MCP` mapping in `tests/test_feature_parity.py`
+4. If the feature is intentionally one-interface-only, add it to `CLI_ONLY` or `MCP_ONLY` with a comment explaining why
+5. Add the tool to `EXPECTED_TOOLS` in `tests/test_mcp_server.py` and `packages/mcp/tests/test_surface_invariants.py`, and to the top entry of `tool_changelog.yaml`
 
 ## Key Conventions
 
-- **Exit codes:** 0=success, 1=error, 2=auth, 3=not found, 4=validation, 5=rate limited (defined in `utils/errors.py`)
+- **Exit codes:** 0=success, 1=error, 2=auth, 3=not found, 4=validation, 5=rate limited, 6=payment required (HTTP 402) (defined in `cited_core/errors.py`, re-exported by `utils/errors.py`)
 - **Line length:** 100 chars (ruff enforced)
 - **All files** start with `from __future__ import annotations`
 - **Type hints** use `X | None` syntax, not `Optional[X]`
@@ -160,6 +163,35 @@ Release, deploy, and infrastructure scripts live in the **private** repo `~/repo
 | dev  | `https://dev.youcited.com` | |
 | local | `http://localhost:8000` | |
 
+## Credits Billing and Agent Identity
+
+Monthly plans (Growth/Scale/Pro), tiers and plan gating were removed entirely. Billing is
+pay-as-you-go credits (1 credit = $1; a standard audit is 10 credits; a one-off audit is $15).
+
+| CLI | MCP tool | Endpoint |
+|-----|----------|----------|
+| `cited credits prices` (no login) | `get_prices` | `GET /billing/prices` |
+| `cited credits balance` | `get_credits` | `GET /billing/credits` |
+| `cited credits history [--limit]` | `credit_history` | `GET /billing/credits/transactions` |
+| `cited credits buy PACK_ID [--no-save-card]` | `buy_credits` | `POST /billing/credits/checkout` |
+| `cited credits buy-audit` | `buy_audit` | `POST /billing/audit-checkout` |
+| `cited credits refund [--yes]` | `request_refund(confirm)` | `POST /billing/credits/refund` |
+| `cited credits redeem CODE` | `redeem_voucher` | `POST /billing/credits/redeem` |
+| `cited credits auto-refill --on/--off [--pack] [--cap]` | `set_auto_refill` | `PUT /billing/credits/auto-refill` |
+| `cited audit quote TEMPLATE_ID [--model]` | `quote_audit` | `POST /billing/audit-quote` |
+| `cited agent signup [--name] [--email]` (no login) | `agent_signup` | `POST /agent/signup` |
+| `cited agent key-status` | `key_status` | `GET /agent/key-status` |
+| `cited agent keys` | `list_api_keys` | `GET /agent-keys` |
+| `cited agent revoke KEY_ID` | `revoke_api_key` | `DELETE /agent-keys/{id}` |
+
+Purchase commands/tools only return a Stripe `checkout_url` for a person to open; they never
+claim a payment happened. Refunds need confirmation (`--yes` in the CLI, `confirm=True` in MCP).
+Vouchers add free credits (once per account per code, claimed accounts only; 404
+`voucher_not_found`, 400 `voucher_expired` / `voucher_used_up`, 409 `voucher_already_redeemed`).
+Signup stores the returned `api_key` with `TokenStore.save_agent_key(env, key)` and never prints
+it; the claim URL and 6-digit code are shown for the human. `cited logout` / the `logout` tool
+forget a saved agent key when there is no session token.
+
 ## Real API Response Field Names (Critical)
 
 These field names were confirmed against the live dev API on 2026-03-18. Using the wrong names produces silently empty output (no error, just blank table cells). Always check the live response shape before adding new field access.

cited_cli-0.5.1/README.md → cited_cli-0.6.0/PKG-INFO

@@ -1,7 +1,36 @@
+Metadata-Version: 2.5
+Name: cited-cli
+Version: 0.6.0
+Summary: CLI for the Cited GEO platform
+Author-email: Cited <support@youcited.com>
+License-Expression: LicenseRef-Proprietary
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cited-core>=0.6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: cited-mcp>=0.6.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: cited-mcp>=0.6.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
 # Cited CLI
 
 Command-line interface for the [Cited](https://youcited.com) GEO (Generative Engine Optimization) platform. Audit how often your business is cited by AI assistants, generate recommendations, and produce AI-ready content solutions — all from the terminal or a Python script.
 
+## For AI agents
+
+- **Free audit, no login:** call the `free_audit` MCP tool (or run `cited audit free example.com`) to see how often ChatGPT, Perplexity and Google AI cite a site, and who they cite instead.
+- **MCP server:** `https://mcp.youcited.com/mcp` (streamable HTTP, OAuth login on first use). Also on PyPI as [`cited-mcp`](https://pypi.org/project/cited-mcp/) for local stdio.
+- **One-command setup:** `cited agent setup` connects Claude Code, Cursor and Codex (and prints the Claude Desktop connector steps). Add `--dry-run` to preview.
+- **Docs:** `search_docs` / `get_doc` tools, or `cited docs search "<question>"`, search the public [Cited docs](https://youcited.com/docs) without a login.
+
 ## Installation
 
 ### Homebrew (recommended)
@@ -73,7 +102,30 @@ cited register --email you@example.com --name "Your Name" --password "Secret123!
 
 ## MCP Server
 
-This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 56 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions on your behalf.
+This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 88 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions on your behalf.
+
+### Quick setup
+
+```bash
+cited agent setup             # configure every AI client found on this machine
+cited agent setup --dry-run   # preview the changes first
+cited agent setup --client cursor --yes
+```
+
+`cited agent setup` merges into your existing config (it never replaces an existing `cited` entry), backs up any file it changes, and supports `--client claude-code|claude-desktop|cursor|codex|all`, `--dry-run`, `--yes` and `--json`. The manual steps for each client follow.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http --scope user cited https://mcp.youcited.com/mcp
+```
+
+Then run `/mcp` in Claude Code and choose **Authenticate**. For Cited slash commands, skills and the `geo-analyst` agent, also install the plugin:
+
+```
+/plugin marketplace add YouCited/cited-plugins
+/plugin install cited@youcited-cited-plugins
+```
 
 ### Claude Desktop (Custom Connector — recommended)
 
@@ -127,7 +179,21 @@ Get your token with `cited login` then `cited auth token`.
 
 ### Cursor
 
-Add a `.cursor/mcp.json` file to your project root (or `~/.cursor/mcp.json` for global access):
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root — or run `cited agent setup --client cursor`:
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "url": "https://mcp.youcited.com/mcp"
+    }
+  }
+}
+```
+
+Open Settings (`Cmd+,`) → **MCP**, click **Login** next to `cited`, and verify it shows a green status. Use tools in Agent mode.
+
+**Fallback** (older Cursor versions without remote-server support) — proxy through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which needs Node.js:
 
 ```json
 {
@@ -140,9 +206,14 @@ Add a `.cursor/mcp.json` file to your project root (or `~/.cursor/mcp.json` for
 }
 ```
 
-Verify Node.js is installed (`node --version`), or install with `brew install node`.
+### Codex
 
-Open Settings (`Cmd+,`) → search "MCP" → verify the server shows a green status. Use tools in Composer (Agent mode).
+```bash
+codex mcp add cited --url https://mcp.youcited.com/mcp
+codex mcp login cited
+```
+
+Or add `[mcp_servers.cited]` with `url = "https://mcp.youcited.com/mcp"` to `~/.codex/config.toml` (`cited agent setup --client codex` does this for you).
 
 ### Updating to new Cited features
 
@@ -161,6 +232,9 @@ Claude will chain the tools automatically — `list_businesses` → `start_audit
 | Category | Tools |
 |----------|-------|
 | **Auth** | `check_auth_status`, `login`, `logout` |
+| **Credits** | `get_prices`, `get_credits`, `credit_history`, `buy_credits`, `buy_audit`, `request_refund`, `redeem_voucher`, `set_auto_refill`, `quote_audit` |
+| **Agent signup & keys** | `agent_signup`, `key_status`, `list_api_keys`, `revoke_api_key` |
+| **No login needed** | `free_audit`, `search_docs`, `get_doc`, `get_prices`, `agent_signup` |
 | **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores`, `get_usage_stats` |
 | **Audit Templates** | `list_audit_templates`, `get_audit_template`, `create_audit_template`, `update_audit_template`, `delete_audit_template` |
 | **Audits** | `start_audit`, `get_audit_status`, `get_audit_result`, `list_audits`, `export_audit` |
@@ -174,6 +248,16 @@ Claude will chain the tools automatically — `list_businesses` → `start_audit
 
 See [`packages/mcp/README.md`](packages/mcp/README.md) for full details, environment variables, and development instructions.
 
+### Pricing: pay-as-you-go credits
+
+No plans or tiers: every command and tool works on every account, and work is paid with
+credits (1 credit = $1). A standard audit is 10 credits (`cited audit quote` shows the exact
+cost); a one-off audit is $15 (`cited credits buy-audit`); packs (`cited credits buy pack_20`)
+need a claimed account. Purchases print a Stripe checkout link for a person to open.
+
+An AI agent with no account can run `cited agent signup` (or call the `agent_signup` tool) to
+get its own API key on an unclaimed account, then give its human the claim link and code.
+
 ---
 
 ## Global Flags
@@ -350,6 +434,13 @@ TEMPLATE_ID=$(cited --json audit template create \
 AUDIT_JOB=$(cited --json audit start $TEMPLATE_ID | jq -r '.job_id')
 cited job watch $AUDIT_JOB
 
+# Optional: compare specific models side by side (see `cited audit models`)
+CMP_JOB=$(cited --json audit start $TEMPLATE_ID \
+  --model anthropic:claude-sonnet-5-5 --model anthropic:claude-opus-5-5 \
+  --model openai:gpt-5.2 | jq -r '.job_id')
+cited job watch $CMP_JOB
+cited audit models $CMP_JOB
+
 RECO_JOB=$(cited --json recommend start $AUDIT_JOB | jq -r '.job_id')
 cited job watch $RECO_JOB
 
@@ -489,7 +580,9 @@ cited config set|get|show|environments
 cited business list|get|create|update|delete|health|crawl
 
 cited audit template list|get|create|update|delete   ← Manage audit templates
+cited audit quote TEMPLATE_ID [--model ...]   ← Credits an audit will cost
 cited audit start|status|result|list|export   ← Run and inspect audits
+cited audit models [JOB_ID]                   ← Compare AI models (or list choices)
 
 cited recommend start|status|result|list      ← Generate recommendations
 cited recommend insights                      ← View actionable source table
@@ -500,8 +593,21 @@ cited hq <business_id> [--full] [--personas] [--products] [--intents] [--actions
 
 cited analytics compare|trends|summary
 
+cited agent setup                             ← Connect Claude Code / Cursor / Codex / Claude Desktop
+cited agent signup [--name] [--email]         ← Account + API key for an AI agent (no login)
+cited agent key-status|keys|revoke KEY_ID     ← Inspect and revoke agent keys
 cited agent facts|claims|comparison|semantic-health|buyer-fit
 
+cited credits prices                          ← Prices and packs (no login; 1 credit = $1)
+cited credits balance|history [--limit N]
+cited credits buy PACK_ID [--no-save-card]    ← Checkout link for a pack
+cited credits buy-audit                       ← $15 checkout link for one audit
+cited credits refund [--yes]                  ← Refund unused credits (last 30 days)
+cited credits redeem CODE                     ← Redeem a voucher code for free credits
+cited credits auto-refill --on|--off [--pack PACK_ID] [--cap USD]
+
+cited docs search|get                         ← Search and read the public docs (no login)
+
 cited job watch|cancel
 ```
 
@@ -521,7 +627,8 @@ cited config set output json    # or "text" (default)
 # Set a default business (used by commands that accept --business)
 cited config set default_business_id <uuid>
 
-# Set Agent API key (for cited agent commands)
+# Use an agent API key instead of `cited login` (sent as X-Agent-API-Key on every
+# request; `cited agent signup` saves one for you). A login session takes precedence.
 cited config set agent_api_key <key>
 
 # Inspect current config
@@ -565,6 +672,7 @@ Errors always go to **stderr** as `{"error": true, "message": "..."}` so they ne
 | 3 | Not found |
 | 4 | Validation error |
 | 5 | Rate limited |
+| 6 | Payment required (not enough credits, or no purchase yet) |
 
 ---
 
@@ -580,7 +688,7 @@ mypy src/cited_cli/ --ignore-missing-imports
 
 ### MCP test harness
 
-`scripts/mcp_test_harness.py` runs an end-to-end test suite against the deployed MCP server (dev or prod). Exercises the four-PR-plan test cases — `tools_fingerprint` on `ping`, `whats_new` lookups, `upgrade_plan` no-op response, `tool_unavailable` error shape — plus auth/host-header/rate-limit/cross-env/`robots.txt` regression checks.
+`scripts/mcp_test_harness.py` runs an end-to-end test suite against the deployed MCP server (dev or prod). Exercises the four-PR-plan test cases — `tools_fingerprint` on `ping`, `whats_new` lookups, read-only credits tools (`get_prices`, `get_credits`), `tool_unavailable` error shape — plus auth/host-header/rate-limit/cross-env/`robots.txt` regression checks.
 
 ```bash
 ./scripts/mcp_test_harness.py --env dev    # mcpdev.youcited.com

cited_cli-0.5.1/PKG-INFO → cited_cli-0.6.0/README.md

@@ -1,29 +1,14 @@
-Metadata-Version: 2.4
-Name: cited-cli
-Version: 0.5.1
-Summary: CLI for the Cited GEO platform
-Author-email: Cited <support@youcited.com>
-License-Expression: LicenseRef-Proprietary
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: cited-core>=0.5.1
-Requires-Dist: rich>=13.0.0
-Requires-Dist: typer>=0.15.0
-Provides-Extra: dev
-Requires-Dist: cited-mcp>=0.5.1; extra == 'dev'
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: respx>=0.21; extra == 'dev'
-Requires-Dist: ruff>=0.4; extra == 'dev'
-Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
-Provides-Extra: mcp
-Requires-Dist: cited-mcp>=0.5.1; extra == 'mcp'
-Description-Content-Type: text/markdown
-
 # Cited CLI
 
 Command-line interface for the [Cited](https://youcited.com) GEO (Generative Engine Optimization) platform. Audit how often your business is cited by AI assistants, generate recommendations, and produce AI-ready content solutions — all from the terminal or a Python script.
 
+## For AI agents
+
+- **Free audit, no login:** call the `free_audit` MCP tool (or run `cited audit free example.com`) to see how often ChatGPT, Perplexity and Google AI cite a site, and who they cite instead.
+- **MCP server:** `https://mcp.youcited.com/mcp` (streamable HTTP, OAuth login on first use). Also on PyPI as [`cited-mcp`](https://pypi.org/project/cited-mcp/) for local stdio.
+- **One-command setup:** `cited agent setup` connects Claude Code, Cursor and Codex (and prints the Claude Desktop connector steps). Add `--dry-run` to preview.
+- **Docs:** `search_docs` / `get_doc` tools, or `cited docs search "<question>"`, search the public [Cited docs](https://youcited.com/docs) without a login.
+
 ## Installation
 
 ### Homebrew (recommended)
@@ -95,7 +80,30 @@ cited register --email you@example.com --name "Your Name" --password "Secret123!
 
 ## MCP Server
 
-This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 56 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions on your behalf.
+This repo also includes `cited-mcp`, a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes 88 tools for AI assistants like Claude. It lets Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions on your behalf.
+
+### Quick setup
+
+```bash
+cited agent setup             # configure every AI client found on this machine
+cited agent setup --dry-run   # preview the changes first
+cited agent setup --client cursor --yes
+```
+
+`cited agent setup` merges into your existing config (it never replaces an existing `cited` entry), backs up any file it changes, and supports `--client claude-code|claude-desktop|cursor|codex|all`, `--dry-run`, `--yes` and `--json`. The manual steps for each client follow.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http --scope user cited https://mcp.youcited.com/mcp
+```
+
+Then run `/mcp` in Claude Code and choose **Authenticate**. For Cited slash commands, skills and the `geo-analyst` agent, also install the plugin:
+
+```
+/plugin marketplace add YouCited/cited-plugins
+/plugin install cited@youcited-cited-plugins
+```
 
 ### Claude Desktop (Custom Connector — recommended)
 
@@ -149,7 +157,21 @@ Get your token with `cited login` then `cited auth token`.
 
 ### Cursor
 
-Add a `.cursor/mcp.json` file to your project root (or `~/.cursor/mcp.json` for global access):
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` in your project root — or run `cited agent setup --client cursor`:
+
+```json
+{
+  "mcpServers": {
+    "cited": {
+      "url": "https://mcp.youcited.com/mcp"
+    }
+  }
+}
+```
+
+Open Settings (`Cmd+,`) → **MCP**, click **Login** next to `cited`, and verify it shows a green status. Use tools in Agent mode.
+
+**Fallback** (older Cursor versions without remote-server support) — proxy through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which needs Node.js:
 
 ```json
 {
@@ -162,9 +184,14 @@ Add a `.cursor/mcp.json` file to your project root (or `~/.cursor/mcp.json` for
 }
 ```
 
-Verify Node.js is installed (`node --version`), or install with `brew install node`.
+### Codex
 
-Open Settings (`Cmd+,`) → search "MCP" → verify the server shows a green status. Use tools in Composer (Agent mode).
+```bash
+codex mcp add cited --url https://mcp.youcited.com/mcp
+codex mcp login cited
+```
+
+Or add `[mcp_servers.cited]` with `url = "https://mcp.youcited.com/mcp"` to `~/.codex/config.toml` (`cited agent setup --client codex` does this for you).
 
 ### Updating to new Cited features
 
@@ -183,6 +210,9 @@ Claude will chain the tools automatically — `list_businesses` → `start_audit
 | Category | Tools |
 |----------|-------|
 | **Auth** | `check_auth_status`, `login`, `logout` |
+| **Credits** | `get_prices`, `get_credits`, `credit_history`, `buy_credits`, `buy_audit`, `request_refund`, `redeem_voucher`, `set_auto_refill`, `quote_audit` |
+| **Agent signup & keys** | `agent_signup`, `key_status`, `list_api_keys`, `revoke_api_key` |
+| **No login needed** | `free_audit`, `search_docs`, `get_doc`, `get_prices`, `agent_signup` |
 | **Businesses** | `list_businesses`, `get_business`, `create_business`, `update_business`, `delete_business`, `crawl_business`, `get_health_scores`, `get_usage_stats` |
 | **Audit Templates** | `list_audit_templates`, `get_audit_template`, `create_audit_template`, `update_audit_template`, `delete_audit_template` |
 | **Audits** | `start_audit`, `get_audit_status`, `get_audit_result`, `list_audits`, `export_audit` |
@@ -196,6 +226,16 @@ Claude will chain the tools automatically — `list_businesses` → `start_audit
 
 See [`packages/mcp/README.md`](packages/mcp/README.md) for full details, environment variables, and development instructions.
 
+### Pricing: pay-as-you-go credits
+
+No plans or tiers: every command and tool works on every account, and work is paid with
+credits (1 credit = $1). A standard audit is 10 credits (`cited audit quote` shows the exact
+cost); a one-off audit is $15 (`cited credits buy-audit`); packs (`cited credits buy pack_20`)
+need a claimed account. Purchases print a Stripe checkout link for a person to open.
+
+An AI agent with no account can run `cited agent signup` (or call the `agent_signup` tool) to
+get its own API key on an unclaimed account, then give its human the claim link and code.
+
 ---
 
 ## Global Flags
@@ -372,6 +412,13 @@ TEMPLATE_ID=$(cited --json audit template create \
 AUDIT_JOB=$(cited --json audit start $TEMPLATE_ID | jq -r '.job_id')
 cited job watch $AUDIT_JOB
 
+# Optional: compare specific models side by side (see `cited audit models`)
+CMP_JOB=$(cited --json audit start $TEMPLATE_ID \
+  --model anthropic:claude-sonnet-5-5 --model anthropic:claude-opus-5-5 \
+  --model openai:gpt-5.2 | jq -r '.job_id')
+cited job watch $CMP_JOB
+cited audit models $CMP_JOB
+
 RECO_JOB=$(cited --json recommend start $AUDIT_JOB | jq -r '.job_id')
 cited job watch $RECO_JOB
 
@@ -511,7 +558,9 @@ cited config set|get|show|environments
 cited business list|get|create|update|delete|health|crawl
 
 cited audit template list|get|create|update|delete   ← Manage audit templates
+cited audit quote TEMPLATE_ID [--model ...]   ← Credits an audit will cost
 cited audit start|status|result|list|export   ← Run and inspect audits
+cited audit models [JOB_ID]                   ← Compare AI models (or list choices)
 
 cited recommend start|status|result|list      ← Generate recommendations
 cited recommend insights                      ← View actionable source table
@@ -522,8 +571,21 @@ cited hq <business_id> [--full] [--personas] [--products] [--intents] [--actions
 
 cited analytics compare|trends|summary
 
+cited agent setup                             ← Connect Claude Code / Cursor / Codex / Claude Desktop
+cited agent signup [--name] [--email]         ← Account + API key for an AI agent (no login)
+cited agent key-status|keys|revoke KEY_ID     ← Inspect and revoke agent keys
 cited agent facts|claims|comparison|semantic-health|buyer-fit
 
+cited credits prices                          ← Prices and packs (no login; 1 credit = $1)
+cited credits balance|history [--limit N]
+cited credits buy PACK_ID [--no-save-card]    ← Checkout link for a pack
+cited credits buy-audit                       ← $15 checkout link for one audit
+cited credits refund [--yes]                  ← Refund unused credits (last 30 days)
+cited credits redeem CODE                     ← Redeem a voucher code for free credits
+cited credits auto-refill --on|--off [--pack PACK_ID] [--cap USD]
+
+cited docs search|get                         ← Search and read the public docs (no login)
+
 cited job watch|cancel
 ```
 
@@ -543,7 +605,8 @@ cited config set output json    # or "text" (default)
 # Set a default business (used by commands that accept --business)
 cited config set default_business_id <uuid>
 
-# Set Agent API key (for cited agent commands)
+# Use an agent API key instead of `cited login` (sent as X-Agent-API-Key on every
+# request; `cited agent signup` saves one for you). A login session takes precedence.
 cited config set agent_api_key <key>
 
 # Inspect current config
@@ -587,6 +650,7 @@ Errors always go to **stderr** as `{"error": true, "message": "..."}` so they ne
 | 3 | Not found |
 | 4 | Validation error |
 | 5 | Rate limited |
+| 6 | Payment required (not enough credits, or no purchase yet) |
 
 ---
 
@@ -602,7 +666,7 @@ mypy src/cited_cli/ --ignore-missing-imports
 
 ### MCP test harness
 
-`scripts/mcp_test_harness.py` runs an end-to-end test suite against the deployed MCP server (dev or prod). Exercises the four-PR-plan test cases — `tools_fingerprint` on `ping`, `whats_new` lookups, `upgrade_plan` no-op response, `tool_unavailable` error shape — plus auth/host-header/rate-limit/cross-env/`robots.txt` regression checks.
+`scripts/mcp_test_harness.py` runs an end-to-end test suite against the deployed MCP server (dev or prod). Exercises the four-PR-plan test cases — `tools_fingerprint` on `ping`, `whats_new` lookups, read-only credits tools (`get_prices`, `get_credits`), `tool_unavailable` error shape — plus auth/host-header/rate-limit/cross-env/`robots.txt` regression checks.
 
 ```bash
 ./scripts/mcp_test_harness.py --env dev    # mcpdev.youcited.com

{cited_cli-0.5.1 → cited_cli-0.6.0}/cited-plugins/CLAUDE_DESKTOP_SETUP.md

@@ -49,10 +49,14 @@ This opens `claude_desktop_config.json`. Add the `mcpServers` section:
 
 Save the file, then quit and reopen Claude Desktop (Cmd+Q on Mac, or close fully on Windows).
 
+> **Shortcut:** if you have the [Cited CLI](https://github.com/YouCited/cited-cli) installed, `cited agent setup --client claude-desktop --desktop-config` adds this entry for you (it merges into your existing config and backs the file up first). Use either the connector (Option A) or this config, not both — otherwise Cited's tools appear twice.
+
 ## Try It Out
 
 Start a new conversation in Claude Desktop and try any of these:
 
+- **"Run a free Cited audit of example.com"** — works before you log in
+
 - **"List my businesses"** — shows all your businesses on Cited
 - **"Run a GEO audit on [business name]"** — audits your AI search presence
 - **"Check my Cited account status"** — verifies you're connected
@@ -83,6 +87,6 @@ Once connected, Claude can:
 - **Generate recommendations** — get actionable insights to improve your AI search visibility
 - **Create solutions** — detailed implementation steps for each recommendation
 - **Check health scores** — see your overall GEO health at a glance
-- **Monitor usage** — check plan limits and account statistics
+- **Monitor usage** — check your credit balance and account statistics
 
 Just ask Claude in plain English — no commands to memorize.

{cited_cli-0.5.1 → cited_cli-0.6.0}/cited-plugins/skills/business-setup/SKILL.md

@@ -9,7 +9,7 @@ Use the Cited MCP tools to create a new business and prepare it for GEO auditing
 
 ## Steps
 
-1. **Verify auth**: Call `check_auth_status` to confirm the user is logged in.
+1. **Verify auth**: Call `check_auth_status` to confirm the user is logged in. If there are no credentials and the user has no account, `agent_signup` creates one for the agent (1 business until a person claims it); show the user the claim link and code it returns.
 
 2. **Create business**: Call `create_business` with:
    - `name`: Business name

{cited_cli-0.5.1 → cited_cli-0.6.0}/cited-plugins/skills/explore/SKILL.md

@@ -7,7 +7,7 @@ description: Ad-hoc tool exploration beyond the standard audit flow — diagnost
 
 The standard pipeline is `cited:business-setup` → `cited:geo-audit` → `cited:geo-recommend`. This skill covers the fourteen tools that DON'T fit that pipeline — diagnostics, deltas, intel surfaces, ad-hoc probes, and Validation Engine fix-verification — so you can answer "what changed since last week," "what does Cited know about this business," "would AI recommend us for X," and "did my fix actually land" without burning a fresh audit.
 
-If a tool returns `payment_required: true` with an `upgrade_tier` field, surface the upgrade message verbatim. Don't pretend the result was empty.
+If a tool returns `payment_required: true` (HTTP 402: `insufficient_credits` or `purchase_required`), tell the user, show them the `buy_url` (or a checkout link from `buy_audit` / `buy_credits`), and retry after they pay. Don't pretend the result was empty.
 
 ## Per-tool reference
 
@@ -23,14 +23,14 @@ What to do with the response: `questions_comparison` is a per-question delta map
 
 ### cancel_job — recovery for hung or wrong-target jobs
 
-When to use it: A `get_*_status` call shows a job has been "running" far longer than expected (audits typically 2-4 min, recommendations 1-2 min, solutions 30-60s) OR the user realizes the job was started against the wrong template/business. Cancelling stops further plan-budget consumption.
+When to use it: A `get_*_status` call shows a job has been "running" far longer than expected (audits typically 2-4 min, recommendations 1-2 min, solutions 30-60s) OR the user realizes the job was started against the wrong template/business. Cancelling a failed or unwanted audit returns its credits.
 
 Recipe:
 1. `cancel_job(job_id=<id>)` — `job_type` auto-probes if omitted.
 
 What to do with the response: `{success, job_type, message}` on success, or a not-found error. Confirm the cancellation by job_type ("audit cancelled," not just "cancelled") and tell the user they can start a fresh job.
 
-### get_analytics_dashboard — combined analytics page (Pro)
+### get_analytics_dashboard — combined analytics page
 
 When to use it: The user asks for an overview of AI search performance — KPIs, trends, top/declining questions, citation patterns, benchmarks. One call covers what the web Analytics page shows.
 
@@ -39,7 +39,7 @@ Recipe:
 
 What to do with the response: Top-level fields are `kpi_trends` (time-series per KPI), `question_performance` (top + declining), `citation_trends` (match rates, domain diversity), `benchmarks` (vs. historical average), `domain_benchmarks` (per-domain severity). Lead the summary with `benchmarks` deltas; then the worst-trending KPI from `kpi_trends`; then the top declining questions.
 
-### get_analytics_trends — KPI time series only (Pro)
+### get_analytics_trends — KPI time series only
 
 When to use it: You only need the KPI time-series — e.g., for a chart, or to compute a custom trend. Cheaper than the dashboard if you don't need the rest.
 
@@ -48,16 +48,16 @@ Recipe:
 
 What to do with the response: `periods` is the x-axis (ordered date labels). `kpi_trends` maps KPI name → list of values aligned with `periods`. `summary` has aggregate stats. Plot or summarize the largest delta first.
 
-### get_business_facts — structured intel from the fact graph (Pro)
+### get_business_facts — structured intel from the fact graph
 
-When to use it: The user asks "what does Cited know about [business]" or you need structured intel (locations, products, summary) without running an audit. Cheap, no plan-budget impact. Pair with crawl_business if the data looks stale.
+When to use it: The user asks "what does Cited know about [business]" or you need structured intel (locations, products, summary) without running an audit. Cheap, uses no credits. Pair with crawl_business if the data looks stale.
 
 Recipe:
 1. `get_business_facts(business_id=<biz_id>)`.
 
 What to do with the response: `name`, `summary`, `locations`, `products`, `facts`. Surface `summary` as the headline. If `summary` is null AND `facts` is empty, the fact graph is thin — recommend running `crawl_business` to populate (see "Cold-start business intel" below).
 
-### get_business_claims — verifiable claims with evidence (Pro)
+### get_business_claims — verifiable claims with evidence
 
 When to use it: Auditing brand truth-in-advertising, or surfacing claims that need stronger evidence before they appear in AI summaries. Useful when prepping a product page or a press kit.
 
@@ -66,7 +66,7 @@ Recipe:
 
 What to do with the response: `claims` is a list of statements with evidence references. Highlight claims with weak/absent evidence first — those are the ones to either substantiate or remove.
 
-### get_business_hq — comprehensive dashboard (Pro)
+### get_business_hq — comprehensive dashboard
 
 When to use it: The user wants a one-shot snapshot of an account — health scores, recent audits, recommendations, competitive position, top action items. Reach for this when summarizing an account holistically rather than answering a narrow question.
 
@@ -76,7 +76,7 @@ Recipe:
 
 What to do with the response: Lead with `health_scores` (5 core scores: brand_confidence, crawl_coverage, ai_readiness, buyer_clarity, trust_score) and `priority_actions` — those tell the user what's wrong and what to fix. `recent_audits` and `recommendations` for activity context. `top_competitors` and `displacement` for competitive context. `agentic_readiness` if the user is asking specifically about AI-agent visibility.
 
-### get_competitive_comparison — strengths/weaknesses vs competitors (Pro)
+### get_competitive_comparison — strengths/weaknesses vs competitors
 
 When to use it: Mid-conversation, the user asks "how do we stack up against X." Pulls existing competitive analysis without running new prompts.
 
@@ -85,7 +85,7 @@ Recipe:
 
 What to do with the response: `competitors` (named competitor entities), `strengths` (top 5-10 wins), `weaknesses` (top 5-10 gaps), `market_intelligence` (supporting observations). Lead with weaknesses if the user is looking for what to fix; lead with strengths if they're pitching/positioning.
 
-### get_semantic_health — AI-readability diagnostics (Pro)
+### get_semantic_health — AI-readability diagnostics
 
 When to use it: The user wants to know what to fix to be more discoverable to AI engines. Returns structured diagnostics rather than free-text recommendations.
 
@@ -94,7 +94,7 @@ Recipe:
 
 What to do with the response: `entity_grounding`, `schema_coverage`, `faq_coverage`, `claim_evidence_coverage` are coverage diagnostics — surface the lowest-coverage area first as the priority fix. `trust_signals` is a list of finding+confidence entries.
 
-### buyer_fit_query — ad-hoc fit simulation (Pro)
+### buyer_fit_query — ad-hoc fit simulation
 
 When to use it: "Would AI recommend us for X" probes — testing positioning before committing to a full audit, or evaluating a new buyer profile. Faster and cheaper than a full audit; doesn't update the business record.
 
@@ -116,7 +116,7 @@ What to do with the response:
 - `get_recommendation_validation_latest`: `status` is the headline — `valid` (fix landed), `invalid` (still missing), `inconclusive` (couldn't verify, often crawler-blocked). `evidence.message` has detail.
 - `get_recommendation_check_status`: lead with `counts` (X valid / Y invalid / Z inconclusive), then surface the invalid checks first — those are the unfixed gaps. Inconclusive results often mean the site blocked the crawler; mention that as a possibility before assuming the fix is broken.
 
-### export_audit — share the report outside MCP (Scale)
+### export_audit — share the report outside MCP
 
 When to use it: The user wants to forward, attach, or archive the audit as a PDF.