# Headless Domains BMOS Integration Skill

This skill file defines how Headless Domains (`headlessdomains.com`) integrates with the BuildMyOnlineStore (BMOS) agentic commerce standard.

## ⚠️ Primary Source of Truth
**For the complete, up-to-date BMOS API, storefront capabilities, and core commerce functionality, agents MUST refer to the official BMOS skill file:**
`https://buildmyonlinestore.com/skill.md`

The documentation below only covers the *integration layer* between Headless Domains and BMOS.

## The Integration Layer

Headless Domains acts as the persistent identity layer (`.agent` and `.chatbot` domains) for BMOS storefronts. The two platforms share tight cross-app trust.

### 1. 1-to-1 Domain Mapping
Headless Domains enforces a strict 1-to-1 mapping between a domain and a BMOS storefront. A single domain cannot host multiple storefronts, and a storefront cannot be bound to multiple domains.

### 2. Bio & Capabilities Injection (`commerce.catalog`)
When a BMOS storefront is successfully bound to a Headless Domain, the integration automatically injects `commerce.catalog` into the agent's manifest capabilities within the `hns_bio`. This allows other agents exploring the Headless Ecosystem to immediately discover that the agent can facilitate commerce.

### 3. DNS TXT Record Generation
The integration automatically provisions a Handshake DNS TXT record formatted as:
`bmos:<feed_url>`
This ensures the commerce feed is resolvable natively at the DNS layer.

### 4. Integration Endpoints
If an agent needs to verify the binding status between a Headless Domain and BMOS, it can use the following endpoint on Headless Domains:

**Check BMOS Binding Status**
`GET /api/v1/domains/<domain_name>/bmos-status`
- **Description**: Verifies if a domain is currently bound to a BMOS storefront.
- **Response**: Returns `is_bound` (boolean) and `storefront_id` (string or null).
- **Note**: This is a public endpoint but is protected by the `LOOKUP_LIMIT` rate limiting.

**Webhook Sync (Internal Use)**
`POST /api/v1/integrations/bmos/sync`
- **Description**: The webhook endpoint used by BMOS to update `domain.hns_bio['commerce_catalog']` and strip it from any other domains globally to enforce uniqueness.
- **Auth**: Requires `BMOS_WEBHOOK_SECRET`.