docs: add starterpack command documentation

.claude/skills/controller-skill/README.md

@@ -148,6 +148,37 @@ You can create custom policy files for your specific contracts and methods.
 13. **controller_config_get** - Get a config value
 14. **controller_config_list** - List all config values
 
+### Starterpacks
+15. **controller_starterpack_info** - Get starterpack metadata (name, description, items)
+16. **controller_starterpack_quote** - Get price quote (payment token, fees, total cost)
+17. **controller_starterpack_purchase** - Purchase a starterpack (`--ui` for browser/crosschain/Apple Pay, `--direct` for on-chain via session)
+
+### Starterpacks
+```
+You: "What's in starterpack #1?"
+
+Claude: [Uses controller starterpack info 1 --chain-id SN_MAIN --json]
+Claude: "Starterpack #1 'Battle Kit' contains: Sword, Shield, 100 Gold"
+```
+
+```
+You: "How much does it cost?"
+
+Claude: [Uses controller starterpack quote 1 --chain-id SN_MAIN --json]
+Claude: "Total cost: 10.70 STRK (base: 10.00, fees: 0.70)"
+```
+
+```
+You: "Buy it for me"
+
+Claude: "Would you like to purchase via browser (supports crosschain/Apple Pay) or directly from your wallet?"
+
+You: "Browser"
+
+Claude: [Uses controller starterpack purchase 1 --chain-id SN_MAIN]
+Claude: "Opening the purchase page — complete payment in your browser."
+```
+
 ## Calldata Formats
 
 Calldata values support multiple formats:

.claude/skills/controller-skill/skill.md

@@ -21,6 +21,7 @@ Use this skill when the user wants to:
 - Check transaction status or receipts
 - Query token balances
 - Look up usernames or addresses
+- Query or purchase starterpacks
 
 ## Tools
 
@@ -652,6 +653,105 @@ controller marketplace buy --order-id 42 --collection 0x123...abc --token-id 1 -
 
 ---
 
+### controller_starterpack_info
+
+Get metadata for a starterpack (name, description, image, items).
+
+**When to use:** To display starterpack details before purchasing.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Starterpack ID (decimal or hex)" },
+    "chain_id": { "type": "string", "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')" },
+    "rpc_url": { "type": "string", "description": "RPC URL (overrides config, conflicts with chain_id)" }
+  },
+  "required": ["id"]
+}
+```
+
+**Example:**
+```bash
+controller starterpack info 1 --chain-id SN_MAIN --json
+```
+
+---
+
+### controller_starterpack_quote
+
+Get a price quote for a starterpack (payment token, fees, total cost).
+
+**When to use:** To check the cost before purchasing.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Starterpack ID (decimal or hex)" },
+    "quantity": { "type": "number", "description": "Quantity to purchase (default: 1)", "default": 1 },
+    "chain_id": { "type": "string", "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')" },
+    "rpc_url": { "type": "string", "description": "RPC URL (overrides config, conflicts with chain_id)" }
+  },
+  "required": ["id"]
+}
+```
+
+**Example:**
+```bash
+controller starterpack quote 1 --chain-id SN_MAIN --json
+```
+
+---
+
+### controller_starterpack_purchase
+
+Purchase a starterpack via UI (browser) or directly from Controller wallet.
+
+**When to use:** To purchase a starterpack for the user or a recipient.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string", "description": "Starterpack ID (decimal or hex)" },
+    "ui": { "type": "boolean", "description": "Open browser UI for purchase (default mode). Supports crosschain payments and Apple Pay." },
+    "direct": { "type": "boolean", "description": "Execute purchase directly via Controller wallet session. Requires approve + issue policies." },
+    "recipient": { "type": "string", "description": "Recipient address (defaults to current controller). Direct mode only." },
+    "quantity": { "type": "number", "description": "Quantity to purchase (default: 1). Direct mode only.", "default": 1 },
+    "chain_id": { "type": "string", "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')" },
+    "rpc_url": { "type": "string", "description": "RPC URL (overrides config, conflicts with chain_id)" },
+    "wait": { "type": "boolean", "description": "Wait for transaction confirmation. Direct mode only.", "default": false },
+    "timeout": { "type": "number", "description": "Timeout in seconds when waiting (default: 300). Direct mode only.", "default": 300 },
+    "no_paymaster": { "type": "boolean", "description": "Pay gas directly instead of using paymaster. Direct mode only.", "default": false }
+  },
+  "required": ["id"]
+}
+```
+
+**`--ui` mode (default):** Opens `https://x.cartridge.gg/starterpack/<ID>/<CHAIN>` in the browser. The user completes payment manually. Supports crosschain payments and Apple Pay.
+
+**`--direct` mode:** Executes `approve` + `issue` on-chain using the active session. The session must have policies for:
+- `approve` on the payment token (check via `starterpack quote`)
+- `issue` on the starterpack contract (`0x3eb03b8f2be0ec2aafd186d72f6d8f3dd320dbc89f2b6802bca7465f6ccaa43`)
+
+**Example (UI):**
+```bash
+controller starterpack purchase 1 --chain-id SN_MAIN
+controller starterpack purchase 1 --ui --chain-id SN_MAIN
+```
+
+**Example (direct):**
+```bash
+controller starterpack purchase 1 --direct --chain-id SN_MAIN --json
+controller starterpack purchase 1 --direct --recipient 0xABC... --quantity 2 --wait --json
+```
+
+---
+
 ## Calldata Formats
 
 Calldata values support multiple formats:

LLM_USAGE.md

@@ -45,6 +45,9 @@ Once installed, tools become available:
 - `controller_username` - Get account username
 - `controller_lookup` - Look up usernames/addresses
 - `controller_config` - Manage CLI configuration
+- `controller_starterpack_info` - Get starterpack metadata
+- `controller_starterpack_quote` - Get starterpack price quote
+- `controller_starterpack_purchase` - Purchase a starterpack (UI or direct)
 
 **See:** [Skill Documentation](./.claude/skills/controller-skill/README.md)
 
@@ -366,6 +369,62 @@ controller config list --json
 
 Valid keys: `rpc-url`, `keychain-url`, `api-url`, `storage-path`, `json-output`, `colors`, `callback-timeout`, `token.<symbol>`.
 
+### 12. Starterpacks
+
+Query starterpack info, get price quotes, and purchase starterpacks.
+
+**Get starterpack metadata:**
+```bash
+controller starterpack info <ID> --chain-id SN_MAIN --json
+```
+
+**Get a price quote:**
+```bash
+controller starterpack quote <ID> --chain-id SN_MAIN --json
+```
+
+Output:
+```json
+{
+  "starterpack_id": "1",
+  "chain_id": "SN_MAIN",
+  "payment_token": "0x04718f...",
+  "base_price": "10.000000",
+  "referral_fee": "0.500000",
+  "protocol_fee": "0.200000",
+  "total_cost": "10.700000"
+}
+```
+
+**Purchase via UI (default — opens browser):**
+```bash
+controller starterpack purchase <ID> --chain-id SN_MAIN
+# or explicitly:
+controller starterpack purchase <ID> --ui --chain-id SN_MAIN
+```
+
+Opens `https://x.cartridge.gg/starterpack/<ID>/<CHAIN>` in the user's browser. The UI supports crosschain payments and Apple Pay — use this when the user wants flexible payment options or doesn't have an active session.
+
+**Purchase directly via Controller wallet:**
+```bash
+controller starterpack purchase <ID> --direct --chain-id SN_MAIN --json
+```
+
+Executes `approve` + `issue` on-chain using the active session. Requires session policies that include:
+- `approve` on the payment token (returned by `quote`)
+- `issue` on the starterpack contract (`0x3eb03b8f2be0ec2aafd186d72f6d8f3dd320dbc89f2b6802bca7465f6ccaa43`)
+
+Additional flags for `--direct`:
+- `--recipient <ADDRESS>` — Purchase for a different address (defaults to controller)
+- `--quantity <N>` — Number to purchase (default: 1)
+- `--wait` — Wait for transaction confirmation
+- `--timeout <SECONDS>` — Timeout when waiting (default: 300)
+- `--no-paymaster` — Pay gas directly instead of using paymaster
+
+**When to use `--ui` vs `--direct`:**
+- `--ui` (default): User wants crosschain payment, Apple Pay, or doesn't have a session with the right policies
+- `--direct`: Automated/scripted purchases where the session already has `approve` + `issue` policies authorized
+
 ---
 
 ### 12. Marketplace Commands

README.md

@@ -253,6 +253,47 @@ MYTOKEN = "0x123..."
 | `CARTRIDGE_RPC_URL` | Default RPC endpoint |
 | `CARTRIDGE_JSON_OUTPUT` | Default to JSON output |
 
+### 11. Starterpacks
+
+Query and purchase starterpacks (bundled game assets).
+
+**Get info:**
+
+```bash
+controller starterpack info <ID> --chain-id SN_MAIN
+```
+
+**Get a price quote:**
+
+```bash
+controller starterpack quote <ID> --chain-id SN_MAIN
+```
+
+**Purchase via UI (default):**
+
+```bash
+controller starterpack purchase <ID> --chain-id SN_MAIN
+# or explicitly:
+controller starterpack purchase <ID> --ui --chain-id SN_MAIN
+```
+
+Opens the Cartridge purchase page in your browser. Supports crosschain payments and Apple Pay.
+
+**Purchase directly from Controller wallet:**
+
+```bash
+controller starterpack purchase <ID> --direct --chain-id SN_MAIN --json
+```
+
+Executes the purchase on-chain using the active session. Requires session policies that include `approve` on the payment token and `issue` on the starterpack contract.
+
+Additional flags for `--direct` mode:
+- `--recipient <ADDRESS>` — Send to a different address (defaults to current controller)
+- `--quantity <N>` — Number to purchase (default: 1)
+- `--wait` — Wait for transaction confirmation
+- `--timeout <SECONDS>` — Confirmation timeout (default: 300)
+- `--no-paymaster` — Pay gas with user funds instead of paymaster
+
 ## Architecture
 
 Built on [`account_sdk`](https://github.com/cartridge-gg/controller-rs) which provides session management, transaction execution, policy validation, and file-based storage. The CLI is a thin wrapper optimized for automation and scripting.