# qrclanka — Agent Skill

You have API access to **qrclanka** (https://www.qrclanka.com) on behalf of the account owner.
qrclanka serves QR codes that open a PIN-gated chat with an agent. This API
lets you create and manage those connections, update their standing context,
queue tasks, and read audit history.

## Auth

Every request needs the user's agent API key:

```
Authorization: Bearer qck_...
```

If you do not have a key, ask the human to create one in their user area at
https://www.qrclanka.com/app → "Agent API". Keys are shown once at creation time. Never send
the key anywhere except https://www.qrclanka.com.

## Endpoints

Base: `https://www.qrclanka.com/api/agent/v1`

| Method | Path | What it does |
|---|---|---|
| GET | `/me` | Your plan, usage (X of 10 free connections), account info |
| GET | `/connections` | List all connections with status, hangup flags, activity |
| POST | `/connections` | Create a connection. Returns `code` + `url` (make a QR from the url) |
| POST | `/connections/:code/context` | Replace the standing context the agent receives |
| POST | `/connections/:code/presets` | Set preset buttons `["Print labels", ...]` and commands `[{label, msg}]` |
| POST | `/connections/:code/pin` | Rotate the PIN (4-8 digits). Also re-enables a locked connection |
| POST | `/connections/:code/disable` | Immediately break a QR code |
| POST | `/connections/:code/enable` | Re-enable, clears PIN strike counter |
| POST | `/connections/:code/task` | Queue a task message for the agent `{ "task": "..." }` |
| GET | `/connections/:code/log` | Job log — the serving agent's own task history |
| POST | `/connections/:code/cooldown` | Hold guest messages N seconds `{ "seconds": 300 }` (0 clears) |
| GET | `/connections/:code/sessions` | Recent guest sessions |
| GET | `/audit?code=...` | Audit trail (unlocks, lockouts, uploads, agent events) |

## Create a connection

```bash
curl -X POST https://www.qrclanka.com/api/agent/v1/connections \
  -H "Authorization: Bearer $QRCLANKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cotton Candy Labels",
    "pin": "4471",
    "pinHint": "Our anniversary month+day",
    "context": "Mel runs a cotton candy business. She needs 5x5 label sheets printed. When she sends a photo, crop it to a square, lay it out on the label template, and print.",
    "presets": ["Print labels from a photo", "Reprint last label", "Check printer"],
    "rateLimit": 20,
    "maxChars": 1000
  }'
```

Response: `{ "code": "k3x9p2", "url": "https://www.qrclanka.com/c/k3x9p2" }`

Render `url` as a QR code and give it to the human (print, save, display).

## Rules

1. **Confirm writes with the human.** Creating connections, rotating PINs,
   disabling — tell the human what you did or are about to do.
2. **PINs are 4-8 digits.** Three wrong attempts break a connection; rotating
   the PIN or an explicit enable restores it.
3. **Context is the scope.** Everything in `context` is given to the agent
   that serves this connection. Keep it tight and specific.
4. **Never delete history.** There is no delete endpoint by design. Disable
   instead.
5. **Free plan = 10 connections.** If `/me` shows the cap is reached, tell
   the human they can unlock lifetime at https://www.qrclanka.com/app.
6. **Hangups matter.** If a connection shows `hangup_flag`, read the audit
   trail and tell the human what the agent got stuck on.

## CLI (preferred)

If the `qrclanka` CLI is on PATH, use it instead of raw curl — same API,
less quoting. One-time setup: `qrclanka auth qck_...` (writes
~/.config/qrclanka/config.json, mode 600). All output is JSON.

```bash
qrclanka me
qrclanka ls
qrclanka new --name "Cotton Candy Labels" --pin 4471 --context "..." --presets "Print labels,Reprint last"
qrclanka qr k3x9p2              # draws the QR in the terminal
qrclanka context k3x9p2 - < new-context.md
qrclanka task k3x9p2 "Check label stock and report"
qrclanka pin k3x9p2 8812        # rotate PIN (also re-enables after lockout)
qrclanka disable k3x9p2
qrclanka audit k3x9p2
```

## Gateway (your machine receives chats through it)

If this machine has no qrclanka gateway yet, mint a key and install:

```bash
qrclanka gateway            # prints a qcg_ key + one-line install command
```

The installer (launchd on macOS, systemd --user on Linux) keeps a persistent
OUTBOUND WebSocket to https://www.qrclanka.com. No open ports, no tunnel. Guest messages for
your connections arrive at the gateway, which runs them through the local
agent (pi by default) and sends replies back. Offline? Messages queue
server-side and flush on reconnect.