# CatalogHub — Agent Interaction Model (agents.txt)

CatalogHub is the structured supplier catalogue network for hospitality. This file describes how
autonomous agents and AI systems are intended to interact with the network.

Status: DRAFT / FORWARD-LOOKING. Endpoints below describe the intended model. Not all
capabilities are generally available today.

## Principles
- One integration, many suppliers. Instead of integrating with every supplier individually,
  agents query a single structured layer.
- Structured over scraped. Product data is normalised, typed, and versioned.
- Observable. Catalogue changes are designed to be monitorable over time.

## Capabilities (intended)
catalog.search        Query supplier catalogues by product, category, attribute, allergen, nutrition, or supplier.
supplier.discover     Surface authorised suppliers and supplier catalogues.
price.compare         Compare prices, pack sizes, unit values, allergens, origin, and availability.
basket.create         Create draft purchase baskets from product identifiers and quantities.
order.submit          Submit approved baskets as orders where enabled.
invoice.query         Query invoice records for authenticated workspaces.
delivery.query        Query delivery and fulfilment records for authenticated workspaces.

## Forward-looking (not yet available)
- Intelligent substitutions across suppliers.
- Multi-supplier optimisation.
- Autonomous ordering and order orchestration outside approved workspace permissions.

## Resources
# Absolute URLs: this file is read by agents that may have fetched it out of
# context (via a cache, an index, or a copy), where a site-relative path cannot
# be resolved.
manifest:          https://cataloghub.hopshq.com/.well-known/agent.json
catalog_manifest:  https://cataloghub.hopshq.com/.well-known/cataloghub-agent.json
overview:          https://cataloghub.hopshq.com/llms.txt
openapi_json:      https://cataloghub.hopshq.com/openapi.json
openapi_yaml:      https://cataloghub.hopshq.com/openapi.yaml
mcp:               https://cataloghub.hopshq.com/mcp
product_schema:    https://cataloghub.hopshq.com/schemas/catalog-product.schema.json
skill:             https://cataloghub.hopshq.com/agent/skill.md

## Etiquette
- Identify your agent via a descriptive User-Agent.
- Respect rate limits and caching headers (planned).
- Prefer monitor subscriptions over polling where available.