Artifacts

# Acme
> One-line description of what Acme does.
## Docs
- [Quickstart](https://acme.com/docs/quickstart.md): get running in 5 minutes
- [API reference](https://acme.com/docs/api.md): endpoints and schemas

<script type="application/ld+json">
{"@context":"https://schema.org","@type":"SoftwareApplication","name":"Acme",
 "description":"Acme helps teams do X.","url":"https://acme.com",
 "offers":{"@type":"Offer","price":"29","priceCurrency":"USD"}}
</script>

GET /docs/quickstart HTTP/1.1
Accept: text/markdown

<link rel="alternate" type="text/markdown" href="/docs/quickstart.md">

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders:write"
Content-Type: application/json

{
  "error": "insufficient_scope",
  "message": "This token cannot write orders.",
  "required_scope": "orders:write",
  "your_scopes": ["orders:read"],
  "grant_at": "https://acme.com/settings/tokens",
  "docs": "https://acme.com/docs/scopes.md"
}

{
  "principal_type": "agent",
  "agent_id": "agt_4f...",
  "owner_user_id": "usr_9a...",
  "scopes": ["orders:read"],
  "revocable": true
}

{
  "name": "Acme",
  "description": "Acme helps teams do X.",
  "auth": { "type": "bearer", "scopes_url": "/docs/scopes.md" },
  "actions": [
    { "name": "search_orders", "method": "GET", "path": "/v1/orders",
      "scopes": ["orders:read"], "description": "Find a customer's orders by email or order ID." },
    { "name": "create_refund", "method": "POST", "path": "/v1/refunds",
      "scopes": ["refunds:write"], "consequential": true,
      "description": "Issue a refund. Irreversible. Supports dry_run." }
  ],
  "docs": "/llms.txt"
}

{
  "order_id": "ord_123",
  "status": "pending_payment",
  "_links": {
    "self":   { "href": "/v1/orders/ord_123" },
    "pay":    { "href": "/v1/orders/ord_123/pay", "method": "POST" },
    "cancel": { "href": "/v1/orders/ord_123/cancel", "method": "POST" }
  }
}

{
  "name": "search_orders",
  "description": "Use this to find a customer's orders by email or order ID. Returns up to 50, newest first. Does not modify anything.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Email or order ID" },
      "limit": { "type": "integer", "default": 20, "maximum": 50 }
    },
    "required": ["query"]
  },
  "examples": [{ "query": "[email protected]", "limit": 10 }]
}

POST /v1/refunds HTTP/1.1
Idempotency-Key: 5f3c...-once-per-intent
X-Dry-Run: true
Content-Type: application/json

{ "order_id": "ord_123", "amount": 4200 }

{ "dry_run": true, "would_refund": 4200, "currency": "usd", "reversible": false,
  "confirm_with": { "header": "X-Dry-Run", "set_to": "false" } }

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "retryable": true,
    "retry_after_seconds": 30,
    "alternative": "Use GET /v1/orders/export for bulk reads.",
    "docs": "https://acme.com/docs/limits.md"
  }
}

{
  "task_id": "task_88a",
  "status": "running",
  "step": 3,
  "of": 5,
  "resumable": true,
  "resume_token": "rt_...",
  "updated_at": "2026-06-04T12:00:00Z"
}

{
  "event": "order.updated",
  "id": "evt_77",
  "occurred_at": "2026-06-04T12:00:00Z",
  "api_version": "2026-06-01",
  "data": { "order_id": "ord_123", "status": "paid" }
}

X-API-Version: 2026-06-01
Sunset: Wed, 31 Dec 2026 23:59:59 GMT

{
  "from_agent": "planner",
  "to_agent": "executor",
  "role": "executor",
  "task": "Issue refund for order ord_123",
  "scope": ["refunds:write"],
  "context": { "order_id": "ord_123", "reason": "duplicate charge" },
  "constraints": { "max_spend_usd": 50, "requires_dry_run": true },
  "return_to": "planner"
}

X-Agent-Request: true
X-Agent-Name: acme-support-bot
X-Agent-Operator: org_acme
User-Agent: acme-support-bot/1.4 (+https://acme.com/agents)

{ "ts": "2026-06-04T12:00:00Z", "agent": "acme-support-bot", "operator": "org_acme",
  "action": "create_refund", "resource": "ord_123", "result": "ok", "reason": "duplicate charge" }

{
  "agent": "acme-support-bot",
  "limits": {
    "requests_per_min": 60,
    "max_spend_usd_per_day": 100,
    "max_actions_per_session": 200,
    "scopes": ["orders:read", "refunds:write"]
  }
}

// Never render agent-produced HTML directly into a trusted page.
// Bad:  element.innerHTML = agentOutput        // injection / XSS
// Bad:  <div dangerouslySetInnerHTML={{__html: agentOutput}} />
// Good: render through a sanitizer with a strict allowlist,
//       or a structured UI spec (for example Google's A2UI), not raw HTML.
const safe = sanitize(agentOutput, { allowedTags: ["b","i","a","p","ul","li","code"] });

[ ] Exists as an API endpoint or MCP tool
[ ] If not: documented reason why human auth is required
[ ] If human auth required: agent can continue after auth (not re-blocked)
[ ] Rate limits and scopes are equivalent to browser/app access
[ ] Error responses are machine-readable (not just HTML error pages)

1. Agent starts work (no account required)
   → Service issues ephemeral resource ID + signed claim URL
   → Agent surfaces claim URL to human: "Your project is live at https://xyz.netlify.app — claim it here: [URL]"

2. Human clicks claim link
   → Service authenticates human (OAuth, magic link, etc.)
   → Resource transfers to human's account
   → Agent session can continue under the now-authenticated context

3. Optional: agent continues with enriched access post-claim

{
  "resource_id": "proj_xyz",
  "resource_url": "https://xyz.example.com",
  "claim_url": "https://example.com/claim?token=abc123&expires=2026-06-07T00:00:00Z",
  "expires_at": "2026-06-07T00:00:00Z",
  "scopes_post_claim": ["deploy", "config", "logs"]
}

{
  "trace_id": "abc123",
  "agent": "claude-code/1.4",
  "session_id": "sess_xyz",
  "task": "deploy_site",
  "outcome": "success",
  "context_sources_used": ["llms.txt", "netlify-mcp"],
  "context_hit_rate": 0.87,
  "time_to_first_tool_call_ms": 1240,
  "tool_calls": 3,
  "tokens_consumed": 4200,
  "feedback": "llms.txt missing blob storage docs — agent fell back to web search"
}