# CatalogHub Agent Skill

A skill describing how an AI agent can work with the CatalogHub supplier catalogue network.

> Status: forward-looking documentation. Endpoints and parameters are illustrative and describe
> the intended interaction model rather than a generally available API.

## What this skill is for

CatalogHub provides a single structured layer for hospitality product data. Use this skill to
search supplier catalogues, compare structured product metadata, monitor changes, and assemble
purchasing recommendations — without integrating with each supplier individually.

## When to use it

- A user (or upstream system) needs to find products across multiple hospitality suppliers.
- You need normalised attributes (pack size, unit, allergens, origin, certifications) to compare.
- You need to detect when a supplier catalogue, price, or availability changes.
- You are assembling a replenishment or purchasing recommendation.

## Core operations (intended)

### Search
```
GET /v1/catalog/search?q=olive+oil&category=oils&region=uk
Authorization: Bearer <token>
```
Returns normalised product records with stable identifiers and supplier references.

### Get a product record
```
GET /v1/products/{product_id}
```
Returns the structured record: identifiers, attributes, pack/unit, supplier, last-updated.

### Monitor changes
```
POST /v1/subscriptions
{ "scope": "supplier:{id}", "events": ["catalog.updated", "price.changed"] }
```

## Example record (illustrative)
```json
{
  "product_id": "ch_prod_8f2a",
  "name": "Extra Virgin Olive Oil",
  "supplier": { "id": "ch_sup_19", "name": "Mediterra Wholesale" },
  "pack": "12 x 1L",
  "unit": "L",
  "attributes": { "origin": "ES", "allergens": [], "organic": true },
  "updated_at": "2026-06-10T08:12:00Z"
}
```

## What NOT to assume

- Do not assume autonomous ordering, substitutions, or multi-supplier optimisation are live.
  These are roadmap items.
- Treat all identifiers and schemas here as indicative until a versioned API is published.

## Related resources
- Overview: /llms.txt
- Interaction model: /agents.txt
- Manifest: /.well-known/cataloghub-agent.json