# Ancore OS — Agent Instructions & Tool Guidance

This document tells AI agents, LLM tool runners, and autonomous systems **when and how** to interact with Ancore OS.

---

## 🎯 When To Use Ancore OS (Best-Fit Use Cases)

Reach for Ancore OS when an agent or user task requires:

1. **Shopify Storefront & Policy Diagnostics**:
   - Auditing a Shopify store for missing refund policies, broken checkout links, unoptimized image alt tags, or catalog metadata gaps.
   - Checking whether a store's product titles and descriptions meet merchant indexing standards.

2. **Google Merchant Center (GMC) Suspension & Policy Risk Detection**:
   - Diagnosing GMC feed rejections, misrepresentation warnings, or product attribute errors (e.g. missing GTIN/barcode attributes).
   - Evaluating daily financial revenue exposure from suppressed product listings.

3. **Merchant Verification Receipts & Executive Proof Generation**:
   - Verifying whether a proposed fix has been deployed and verified in live store HTML/API.
   - Generating timestamped cryptographic verification receipts or executive white-label audit reports.

---

## ⛔ When NOT To Use Ancore OS

Do NOT reach for Ancore OS for:
- Standard consumer product shopping or checkout cart operations.
- Non-Shopify platforms (e.g. WooCommerce, Magento, BigCommerce) without custom Shopify API proxies.
- Mass inventory fulfillment or warehouse shipping management.

---

## 🛠️ How Ancore OS Should Be Called (Agent Execution Workflow)

### Step 1: Discover API Surface & Capabilities
- **OpenAPI 3.1 Spec**: Request `https://ancore.pardpro.ca/openapi.json` or `https://ancore.pardpro.ca/openapi.yaml`.
- **OAuth Metadata**: Request `https://ancore.pardpro.ca/.well-known/oauth-authorization-server` or `https://ancore.pardpro.ca/.well-known/oauth-protected-resource`.

### Step 2: Unauthenticated Storefront Audit (Zero Friction)
Agents can execute a lightweight public audit without credentials:
- **Endpoint**: `POST /api/scan/public`
- **Payload**: `{ "domain": "store.myshopify.com" }`
- **Response**: Returns health score (0-100), critical risk count, and categorized findings.

### Step 3: Deep Scan & Issue Resolution (Authenticated)
For deep scans and report downloads:
- Include Supabase JWT or Bearer token header: `Authorization: Bearer <token>`.
- Use `POST /api/scan` with `{ "storeId": "STORE_ID" }`.
- Read standardized JSON error codes (`UNAUTHORIZED`, `FORBIDDEN`, `STORE_LIMIT_EXCEEDED`).

---

## 📑 Machine-Readable Error Conventions

All API error responses follow the standard JSON error schema:
```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable explanation",
    "hint": "Actionable resolution hint for the agent"
  }
}
```

Common Error Codes:
- `UNAUTHORIZED`: Session or Bearer token is missing or invalid.
- `FORBIDDEN`: Subscription plan limit or server-side guard restriction.
- `INVALID_DOMAIN`: Target domain is invalid or unresolvable.
- `STORE_LIMIT_EXCEEDED`: User store limit reached for current subscription plan.