feat: add marketplace commands (buy, info)

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

@@ -550,6 +550,108 @@ controller config set token.MYTOKEN 0x123...
 
 ---
 
+### controller_marketplace_info
+
+Query marketplace order validity before purchasing.
+
+**When to use:** To check if a marketplace order is valid and can be purchased.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "order_id": {
+      "type": "integer",
+      "description": "The marketplace order ID"
+    },
+    "collection": {
+      "type": "string",
+      "description": "NFT collection contract address"
+    },
+    "token_id": {
+      "type": "string",
+      "description": "Token ID in the collection"
+    },
+    "chain_id": {
+      "type": "string",
+      "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')"
+    }
+  },
+  "required": ["order_id", "collection", "token_id"]
+}
+```
+
+**Example:**
+```bash
+controller marketplace info --order-id 42 --collection 0x123...abc --token-id 1 --chain-id SN_MAIN --json
+```
+
+---
+
+### controller_marketplace_buy
+
+Purchase an NFT from a marketplace listing.
+
+**When to use:** To buy an NFT from an active marketplace order.
+
+**Input Schema:**
+```json
+{
+  "type": "object",
+  "properties": {
+    "order_id": {
+      "type": "integer",
+      "description": "The marketplace order ID to purchase"
+    },
+    "collection": {
+      "type": "string",
+      "description": "NFT collection contract address"
+    },
+    "token_id": {
+      "type": "string",
+      "description": "Token ID in the collection"
+    },
+    "asset_id": {
+      "type": "string",
+      "description": "Asset ID for ERC1155 tokens (defaults to 0)"
+    },
+    "quantity": {
+      "type": "integer",
+      "description": "Quantity to purchase (defaults to 1)"
+    },
+    "no_royalties": {
+      "type": "boolean",
+      "description": "Skip paying creator royalties"
+    },
+    "chain_id": {
+      "type": "string",
+      "description": "Chain ID (e.g., 'SN_MAIN' or 'SN_SEPOLIA')"
+    },
+    "wait": {
+      "type": "boolean",
+      "description": "Wait for transaction confirmation"
+    },
+    "no_paymaster": {
+      "type": "boolean",
+      "description": "Pay gas yourself instead of using paymaster"
+    }
+  },
+  "required": ["order_id", "collection", "token_id"]
+}
+```
+
+**Example:**
+```bash
+controller marketplace buy --order-id 42 --collection 0x123...abc --token-id 1 --chain-id SN_MAIN --wait --json
+```
+
+**Required Session Policies:**
+- `execute` on marketplace contract (`0x057b4ca2f7b58e1b940eb89c4376d6e166abc640abf326512b0c77091f3f9652`)
+- `approve` on payment token (e.g., STRK)
+
+---
+
 ## Calldata Formats
 
 Calldata values support multiple formats:

AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md — Contributing Guidelines
+
+Guidelines for AI agents and human contributors working on this codebase.
+
+## Before You Code
+
+1. **Read the docs** — `README.md`, `LLM_USAGE.md`, and relevant source files
+2. **Understand the architecture** — This is a thin CLI wrapper around [`account_sdk`](https://github.com/cartridge-gg/controller-rs)
+3. **Check existing patterns** — Follow the style of existing commands in `src/commands/`
+
+## Code Style
+
+### Rust Standards
+
+- **Format**: Run `cargo fmt` before committing
+- **Lint**: Run `cargo clippy` and fix warnings
+- **Build**: Ensure `cargo build` succeeds
+- **Test**: Run `cargo test` if tests exist
+
+### CLI Conventions
+
+- All commands support `--json` for machine-readable output
+- Use the `JsonOutput` struct for consistent response format
+- Include `error_code`, `message`, and `recovery_hint` in error responses
+- Add new commands to `src/commands/mod.rs`
+
+### Documentation
+
+- Update `LLM_USAGE.md` when adding/modifying commands
+- Update `SKILL.md` when adding new tools for agents
+- Include examples in doc comments
+
+## PR Guidelines
+
+### Before Opening a PR
+
+```bash
+# Required checks
+cargo fmt
+cargo clippy
+cargo build
+cargo test  # if tests exist
+```
+
+### PR Title Format
+
+```
+type(scope): description
+
+# Examples:
+feat(marketplace): add buy and info commands
+fix(session): handle expired token refresh
+docs(readme): add calldata format examples
+```
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+### PR Description
+
+Include:
+- **What** — Brief description of changes
+- **Why** — Motivation or issue being solved
+- **How** — Technical approach if non-obvious
+- **Testing** — How you verified the changes work
+
+### Commit Messages
+
+- Use conventional commits format
+- Keep subject line under 72 characters
+- Reference issues with `#123` if applicable
+
+## Adding New Commands
+
+1. Create a new file in `src/commands/` (or a subdirectory for command groups)
+2. Implement the command struct with clap derive macros
+3. Add to the command enum in `src/commands/mod.rs`
+4. Add the subcommand variant in `src/main.rs`
+5. Update `LLM_USAGE.md` with usage examples
+6. Update `.claude/skills/controller-skill/skill.md` if it's agent-relevant
+
+### Command Structure
+
+```rust
+use clap::Parser;
+use crate::utils::output::JsonOutput;
+
+#[derive(Parser, Debug)]
+pub struct MyCommand {
+    /// Description of the argument
+    #[arg(long)]
+    pub some_arg: String,
+}
+
+impl MyCommand {
+    pub async fn run(&self, config: &Config) -> Result<()> {
+        // Implementation
+    }
+}
+```
+
+## Security Considerations
+
+- Never log or output private keys
+- Session credentials stay in `~/.config/controller-cli/`
+- Validate all user inputs
+- Use `--json` output for programmatic access (no parsing stdout text)
+
+## Getting Help
+
+- [Controller Docs](https://docs.cartridge.gg/controller)
+- [Starknet Docs](https://docs.starknet.io/)
+- [account_sdk source](https://github.com/cartridge-gg/controller-rs)

LLM_USAGE.md

@@ -368,6 +368,67 @@ Valid keys: `rpc-url`, `keychain-url`, `api-url`, `storage-path`, `json-output`,
 
 ---
 
+### 12. Marketplace Commands
+
+Buy NFTs from the Arcade marketplace.
+
+#### Query Order Info
+
+Check if an order is valid before purchasing:
+
+```bash
+controller marketplace info \
+  --order-id 42 \
+  --collection 0x123...abc \
+  --token-id 1 \
+  --chain-id SN_MAIN \
+  --json
+```
+
+Output:
+```json
+{
+  "order": {
+    "order_id": 42,
+    "collection": "0x123...abc",
+    "token_id": "1",
+    "is_valid": true,
+    "validity_reason": "Order is valid"
+  }
+}
+```
+
+#### Buy from Listing
+
+Purchase an NFT from an active marketplace listing:
+
+```bash
+controller marketplace buy \
+  --order-id 42 \
+  --collection 0x123...abc \
+  --token-id 1 \
+  --chain-id SN_MAIN \
+  --wait \
+  --json
+```
+
+Options:
+- `--order-id` (required): The marketplace order ID
+- `--collection` (required): NFT collection contract address
+- `--token-id` (required): Token ID in the collection
+- `--asset-id`: Specific asset ID for ERC1155 (defaults to 0)
+- `--quantity`: Number to purchase (defaults to 1)
+- `--no-royalties`: Skip paying creator royalties
+- `--wait`: Wait for transaction confirmation
+- `--no-paymaster`: Pay gas yourself instead of using paymaster
+
+**Required Session Policies:**
+Your session must include policies for:
+- `execute` on the marketplace contract (`0x057b4ca2f7b58e1b940eb89c4376d6e166abc640abf326512b0c77091f3f9652`)
+- `approve` on the payment token (e.g., STRK)
+
+---
+
 ## Calldata Formats
 
 Calldata values support multiple formats:

SKILL.md

@@ -106,6 +106,37 @@ controller config list --json          # List all config values
 
 Valid keys: `rpc-url`, `keychain-url`, `api-url`, `storage-path`, `json-output`, `colors`, `callback-timeout`, `token.<symbol>`.
 
+### Marketplace
+
+Buy NFTs from the Arcade marketplace.
+
+```bash
+# Check if an order is valid
+controller marketplace info \
+  --order-id 42 \
+  --collection 0x123...abc \
+  --token-id 1 \
+  --chain-id SN_MAIN --json
+
+# Purchase from a listing
+controller marketplace buy \
+  --order-id 42 \
+  --collection 0x123...abc \
+  --token-id 1 \
+  --chain-id SN_MAIN \
+  --wait --json
+```
+
+Options:
+- `--order-id`: Marketplace order ID
+- `--collection`: NFT collection address
+- `--token-id`: Token ID to purchase
+- `--asset-id`: Asset ID for ERC1155 (default: 0)
+- `--quantity`: Amount to buy (default: 1)
+- `--no-royalties`: Skip creator royalties
+
+Required session policies: `execute` on marketplace contract, `approve` on payment token.
+
 ## Calldata Format
 
 - Values are comma-separated