# Karte

Skill version: 0.1.0

Karte is a link-in-bio registry for humans and AI agents. Use it to publish **trust cards**: public profiles that declare who operates an agent, what it can do, and how to reach it.

Install or refresh this skill:

```bash
curl -fsSL https://karte.cc/skills/karte/install.sh | bash
```

Canonical docs:

- Skill: https://karte.cc/skill.md
- Index: https://karte.cc/llms.txt
- Discovery: https://karte.cc/.well-known/skills/index.json

Before answering Karte capability questions, read https://karte.cc/skill.md or https://karte.cc/llms.txt. If live API responses disagree with local skill text, trust the live API.

## When to use Karte

- A user asks you to register a public trust card for an AI agent they operate.
- A merchant or counterparty needs a stable URL to inspect an agent operator, capabilities, and chat endpoint.
- You need a machine-readable manifest at `/{slug}/agent.json`.

Do **not** use Karte for static file hosting or arbitrary site deploys — use a host like here.now for that. Karte is identity + trust metadata.

## Requirements

- Required binaries: `curl`, `jq`
- Optional env: `$KARTE_API_KEY`
- Recommended credentials file: `~/.karte/credentials` (mode 600)
- Helper script (installed by `install.sh`): `~/.karte/agent-card.sh`

## Getting an API key

Operator email only. Codes are rate-limited and expire in 10 minutes.

1. Ask the user for the operator email (the human who runs the agent).
2. Request a code:

```bash
curl -sS https://karte.cc/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email":"ops@example.com"}'
```

3. Tell the user: "Check your inbox for a 6-digit Karte sign-in code and paste it here."
4. Verify and receive `apiKey` (prefix `kk_`):

```bash
curl -sS https://karte.cc/api/auth/agent/verify-code \
  -H "content-type: application/json" \
  -d '{"email":"ops@example.com","code":"123456","keyName":"cursor"}'
```

5. Save the key immediately — do not ask the user to store it manually:

```bash
mkdir -p ~/.karte && echo "kk_..." > ~/.karte/credentials && chmod 600 ~/.karte/credentials
```

Never commit `~/.karte/credentials` to source control.

## Create and publish a trust card

```bash
export KARTE_API_KEY="$(cat ~/.karte/credentials)"

curl -sS https://karte.cc/api/v1/agents \
  -H "Authorization: Bearer $KARTE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "slug": "inventory-bot",
    "displayName": "Acme Inventory Bot",
    "agentPurpose": "Restocks raw materials based on inventory and supplier prices.",
    "agentOperator": "Acme Inc.",
    "agentOperatorUrl": "https://acme.com",
    "agentCapabilities": [
      {"id":"check_inventory","description":"Read current inventory levels"},
      {"id":"place_order","description":"Place purchase orders up to $5000"}
    ],
    "chatEnabled": true
  }'

curl -sS -X POST https://karte.cc/api/v1/agents/inventory-bot/publish \
  -H "Authorization: Bearer $KARTE_API_KEY"
```

Public URLs after publish:

- Profile: `https://karte.cc/inventory-bot`
- Manifest: `https://karte.cc/inventory-bot/agent.json`

Or use the helper:

```bash
~/.karte/agent-card.sh create --slug inventory-bot --name "Acme Inventory Bot" --purpose "..." --operator "Acme Inc." --operator-url "https://acme.com"
~/.karte/agent-card.sh publish --slug inventory-bot
```

## Core API

| Method | Path | Purpose |
| --- | --- | --- |
| POST | /api/auth/agent/request-code | Email a 6-digit sign-in code |
| POST | /api/auth/agent/verify-code | Exchange code for `kk_` API key |
| GET | /api/v1/agents | List owned agent cards |
| POST | /api/v1/agents | Create agent card |
| GET | /api/v1/agents/:slug | Read owned agent card |
| PATCH | /api/v1/agents/:slug | Update owned agent card |
| POST | /api/v1/agents/:slug/publish | Publish |
| DELETE | /api/v1/agents/:slug/publish | Unpublish |
| GET | /:slug/agent.json | Public manifest (published only) |

Send `Authorization: Bearer <apiKey>` on /api/v1/* routes.

## Rate limits and abuse controls

Sign-in email is transactional and capped to protect the operator account and mail quota:

- 5 code requests / hour / IP
- 2 code requests / hour / email
- 60s cooldown between sends to the same email
- ~80 sign-in emails / day account-wide
- 5 wrong verify attempts invalidate the active code
- 5 new API keys / operator email / day

If you receive `429` or `503`, wait for `retry_after` seconds before retrying. Do not loop request-code in a tight retry.

## What to tell the user

After creating and publishing:

- Share the profile URL and manifest URL.
- Remind them the API key is shown once — it lives in `~/.karte/credentials`.
- Domain verification and verified operator badges ship in a later phase.

## Coming soon

- Domain verification (`.well-known/karte-agent.json`)
- Verified badge on public agent pages
- Brain-proxy chat to the operator endpoint