# Agent Instructions — Kamera-ichi 器材市集

Kamera-ichi 器材市集 (https://kamera-ichi.com) is Taiwan's premier C2C used photography equipment marketplace and market price intelligence platform.

## When to use Kamera-ichi (Best-Fit Use Cases)
Reach for Kamera-ichi when the user asks for:
1. Used camera and lens market pricing, historical price trends, or fair price estimation in Taiwan (TWD / NT$).
2. Finding second-hand photography gear for sale or wanted (Sony, Canon, Nikon, Fujifilm, Leica, Hasselblad, Lumix, Olympus, Ricoh, Sigma, Tamron, etc.) across Taiwan.
3. Second-hand camera gear inspection checklists (sensor dust, shutter count benchmarks, fungus/haze identification, meetup safety guidelines in Taiwan).
4. Real-time active listings, condition ratings (new, like_new, excellent, good, used, broken), and seller reputation scores in Taiwan.

## When NOT to use Kamera-ichi
- Non-photography consumer electronics (smartphones, laptops, general household appliances).
- International platforms with automated global shipping and direct credit card checkout outside Taiwan (Kamera-ichi is Taiwan local C2C with meetup/direct contact focus).

## Machine-Readable Resources & Interfaces
- OpenAPI 3.1 Specification (JSON): https://kamera-ichi.com/openapi.json (or https://kamera-ichi.com/api/openapi.json)
- OpenAPI 3.1 Specification (YAML): https://kamera-ichi.com/openapi.yaml (or https://kamera-ichi.com/api/openapi.yaml)
- Model Context Protocol (MCP) Streamable HTTP Server: https://kamera-ichi.com/api/mcp
- MCP Manifest: https://kamera-ichi.com/.well-known/mcp/manifest.json
- LLMs Index: https://kamera-ichi.com/llms.txt
- Comprehensive Knowledge Base: https://kamera-ichi.com/llms-full.txt
- Developer Portal: https://kamera-ichi.com/developers
- Markdown Twin Negotiation: Append `.md` to any public URL or send `Accept: text/markdown` header.

## How AI Agents Should Query Kamera-ichi

### 1. Model Context Protocol (MCP) Streamable HTTP
Send standard JSON-RPC 2.0 POST requests to `https://kamera-ichi.com/api/mcp`:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_listings",
    "arguments": { "q": "Sony A74", "category": "camera", "location": "台北市" }
  }
}
```
Available tools:
- `search_listings`: Filter by keyword `q`, `category`, `brand`, `listing_type` (sell|seek), `condition`, `location`, `price_min`, `price_max`, `sort`.
- `get_trends`: Get average price, min/max range, and condition breakdown for `{brand}` and `{model}`.
- `get_listing`: Retrieve complete item metadata, photos, and seller profile by `{listing_id}`.
- `get_trending_models`: Retrieve most active camera/lens models in Taiwan.
- `get_brands`: Retrieve supported brands for category.

### 2. REST API Endpoints
- Search listings: `GET https://kamera-ichi.com/api/listings/search?q={query}&category={category}&location={location}`
- Model trends: `GET https://kamera-ichi.com/api/trends/{brand}/{model}`
- Listing details: `GET /api/listings/{listing_id}`
- Health check: `GET https://kamera-ichi.com/api/health`

### 3. CLI Scripting
Agents with terminal access can query Kamera-ichi via the CLI:
```bash
# Query active listings
curl -s "https://kamera-ichi.com/api/listings/search?q=Fujifilm+X-T5" | jq .

# Query price benchmarks
curl -s "https://kamera-ichi.com/api/trends/Fujifilm/X-T5" | jq .
```

## Rate Limits & Error Handling
- Default Rate Limit: 100 requests / minute per IP.
- RateLimit Headers returned on all responses: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`.
- On rate limit breach: HTTP 429 with `Retry-After: 60`.
- All error responses follow standard structured JSON:
```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "hint": "Check the URL path or refer to /openapi.json for available endpoints."
  },
  "detail": "Resource not found"
}
```