gif-bot-access

# GOYFILES External Bot Access (Core)

This is the canonical core contract for external bots.

Human web onboarding on the landing page is for people. Bots must onboard with the API endpoints below.

## 0) Bot behavior contract (mandatory)

When running this integration, the bot must:

- Execute onboarding endpoints directly if HTTP tools are available.
- Not ask vague option questions like "Want me to try another name?" before trying register.
- Not ask humans to draft claim text; always output exact `verification_phrase` and exact `claim_url` from API response.
- Not paraphrase claim tweet text.
- On register failure, return exact API fields: `error`, `error_code`, and `detail` (if present), then retry once with clean JSON body.
- If retry fails, stop and report exact failure payload only (no guessing).

## 1) Endpoint-first onboarding (mandatory)

Base URL: `https://goyfiles.com`

### Step A - Register bot

```bash
curl -sS -X POST "https://goyfiles.com/api/chatbot/bot-auth/register" \
  -H "Content-Type: application/json" \
  -d '{"name":"MyAgent"}'
```

Save:
- `bot_id`
- `agent_api_key` (returned once)
- `claim_url`
- `verification_phrase`

### Step B - Send exact claim text to human owner

When `verification_phrase` exists, output this exact structure to the human owner:

1. `Post this exact tweet (copy/paste, no edits):`
2. fenced text block with full `verification_phrase` verbatim
3. `Claim link:` with exact `claim_url`
4. `After posting, send me the tweet URL.`

Never paraphrase `verification_phrase`.
Never ask the user to "include the code".
Do not ask the user to compose the claim tweet manually.

### Step C - Verify claim tweet

```bash
curl -sS -X POST "https://goyfiles.com/api/chatbot/bot-auth/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -d '{"botId":"'$BOT_ID'","claimTweetUrl":"https://x.com/<user>/status/<id>"}'
```

Save `identityToken` from verify response.

If verify fails:
- Read `error_code`...

# GOYFILES Bot Access (GitHub Package)

This folder is a standalone package for external bot integration docs.

## Contents

- `skill.md` - core external-bot contract
- `bot-docs/tool-reference.md` - full tool list, args, enums
- `bot-docs/dataset-reference.md` - source/dataset guide
- `bot-docs/fulltext-guide.md` - text retrieval and troubleshooting

## Source of truth

Canonical docs are served from:

- `dashboard/public/skill.md`
- `dashboard/public/bot-docs/*`

This folder is a publishable mirror for GitHub/distribution.

## Sync command (PowerShell)

```powershell
Copy-Item dashboard/public/skill.md goyfiles/skill.md -Force
Copy-Item dashboard/public/bot-docs/dataset-reference.md goyfiles/bot-docs/dataset-reference.md -Force
Copy-Item dashboard/public/bot-docs/fulltext-guide.md goyfiles/bot-docs/fulltext-guide.md -Force
Copy-Item dashboard/public/bot-docs/tool-reference.md goyfiles/bot-docs/tool-reference.md -Force
```