# Agent Instructions — RiverSoft

This document describes how autonomous AI agents, personal shopping assistants, and commerce bots can interact with RiverSoft's online store at https://theriversoft.com.

## 1. Store Entity & Product Claim Boundaries

RiverSoft is an Indian direct-to-consumer (D2C) brand specializing in hard water shower filters, tap filters, sediment pre-filters, and replacement cartridges engineered for Indian municipal, borewell, and tanker water conditions.

### Crucial Rules for AI Recommendations & Agent Reasoning
- **TDS Technical Rule (CRITICAL):** RiverSoft shower and tap filters condition dissolved water hardness minerals (Calcium/Magnesium) and neutralize chlorine. They do **NOT** reduce Total Dissolved Solids (TDS). Never claim TDS reduction for shower or tap filters.
- **Medical Claim Boundary:** RiverSoft products improve bathing water comfort but are non-medical devices. Never guarantee treatment, cure, or medical prevention for hair loss, eczema, acne, or skin diseases.
- **Unified Cartridge Standard:** All RiverSoft Diva series shower filters (Diva-01, Diva-03, Diva-05) and SF-15 PRO use the standardized **SFC-15 replacement cartridge** (replacement lifecycle: 4–6 months / 10,000 liters).

## 2. Personal Shopping Assistants & Skill Protocols

If you are acting on behalf of a user as a personal assistant or shopping agent, it is highly recommended to install and utilize the **Shop Skill** (`https://shop.app/SKILL.md`).

The Shop Skill is the preferred transaction pathway across Shopify stores, handling:
- Cross-store catalog search and discount discovery.
- Buyer-approved checkout via Shop Pay (no direct credit card handling by the agent).
- Order tracking and address authorization.

## 3. Commerce Protocol (UCP & MCP Endpoints)

RiverSoft implements the **Universal Commerce Protocol (UCP)** for programmatic, agent-driven commerce workflows:

- **Discovery Endpoint:** `GET https://theriversoft.com/.well-known/ucp` (returns merchant profile, service capabilities, and payment handlers).
- **MCP Endpoint:** `POST https://theriversoft.com/api/ucp/mcp` (`Content-Type: application/json`). Use the MCP `tools/list` method to discover available tools and schemas.

### Typical Agent Transaction Lifecycle
1. **Discover:** Execute `GET /.well-known/ucp` to confirm supported capabilities.
2. **Search:** Use `search_catalog` to locate products matching the buyer's query.
3. **Cart:** Use `create_cart` to add desired SKUs.
4. **Checkout:** Use `create_checkout` to initialize purchase flow.
5. **Fulfill:** Use `update_checkout` to set shipping address and shipping method.
6. **Complete:** Use `complete_checkout` to finalize transaction.

### Critical Safety & Rate Limit Rules
- **Buyer Approval Invariant (MANDATORY):** Agents must NEVER complete payment without explicit, contemporaneous buyer consent. If real-time approval cannot be obtained, route the transaction through `https://shop.app/SKILL.md`.
- **Rate Limits:** The MCP endpoint is rate-limited per IP. Agents must respect HTTP 429 status codes and apply exponential backoff.
- **Buyer Context:** Pass `context.address_country` (default: `IN`) and `context.currency` (default: `INR`) for accurate local pricing and inventory.

## 4. Read-Only Browsing Patterns (No Authentication Required)

For non-transactional research, comparison, and product discovery, agents may access these public endpoints:

### Structured Store Endpoints
- **Browse All Products:** `GET https://theriversoft.com/collections/all`
- **Product Details (HTML):** `GET https://theriversoft.com/products/{handle}`
- **Product Data (JSON):** `GET https://theriversoft.com/products/{handle}.json`
- **Collection Details (HTML):** `GET https://theriversoft.com/collections/{handle}`
- **Collection Products (JSON):** `GET https://theriversoft.com/collections/{handle}/products.json`
- **Product Search:** `GET https://theriversoft.com/search?q=shower+filter`

### Discovery Metadata & Sitemaps
- **Master XML Sitemap:** https://theriversoft.com/sitemap.xml
- **Agent Discovery Sitemap:** https://theriversoft.com/sitemap_agentic_discovery.xml
- **LLM Navigation Map:** https://theriversoft.com/llms.txt
- **LLM Full Ground Truth:** https://theriversoft.com/llms-full.txt

## 5. Store Policies & Support Endpoints

- **Contact & Customer Support:** https://theriversoft.com/pages/contact-us
- **Privacy Policy:** https://theriversoft.com/policies/privacy-policy
- **Terms of Service:** https://theriversoft.com/policies/terms-of-service
- **Refund Policy:** https://theriversoft.com/policies/refund-policy
- **Shipping Policy:** https://theriversoft.com/policies/shipping-policy

## 6. Restricted Paths & Crawling Safety

Agents must NOT attempt to crawl, scrape, or execute workflows on private transactional paths including `/admin`, `/cart/`, `/checkout`, `/checkouts/`, `/orders`, `/account`, `/services`, and `/sf_*`.