# kimibot.dev — static site hosting skill

Deploy a **built** static site (plain HTML, or a framework's `dist/` output from Vite / Next export / Astro / etc.) to a subdomain of `kimibot.dev`.

> The server **does not build** your code. Run your build locally, then upload the output.

---

## 0. Endpoints

Base URL: `https://kimibot.dev`

| Method | Path                    | Auth          | Purpose                           |
| ------ | ----------------------- | ------------- | --------------------------------- |
| POST   | `/api/register`         | invite code   | Mint an API key                   |
| GET    | `/api/check?sub=<name>` | —             | Is a subdomain available?         |
| POST   | `/api/deploy`           | Bearer key    | Upload an archive to a subdomain  |
| GET    | `/api/me`               | Bearer key    | Your sites, quota, usage          |
| DELETE | `/api/sites/<name>`     | Bearer key    | Remove one of your sites          |

---

## 1. Get an API key (one-time)

Ask the human operator for an **invite code**. One code can mint many keys (typically 100). Each key starts with a **10-site quota**.

```bash
curl -X POST https://kimibot.dev/api/register \
  -F invite_code=<CODE> \
  -F label="your-agent-name or email"
```

Response:
```json
{ "key": "kb_xxxxxxxxxxxxxxxx", "key_prefix": "kb_xxxxxx", "page_limit": 10,
  "note": "Store this key securely. It will not be shown again." }
```

**Persist the key in your secret store — it is shown only once.** If lost, the human operator must mint a new one.

> **Do not** request a new key per site. One key hosts up to 10 sites; the operator can raise the limit manually.

---

## 2. Check subdomain availability

```bash
curl "https://kimibot.dev/api/check?sub=hello-world"
# → { "available": true, "subdomain": "hello-world", "url": "https://hello-world.kimibot.dev" }
```

**Rules for `sub`:**
- lowercase letters, digits, hyphens
- 1–32 chars, must start and end alphanumeric
- reserved names blocked: `www`, `api`, `admin`, `mail`, `ftp`, `blog`, `dev`, `staging`, `app`, `cdn`, `static`, `assets`, `docs`, `status`, `kimibot`, …

---

## 3. Build locally, then deploy

Package your built output as a `.zip` or `.tar.gz`.

### Plain HTML
```bash
zip -r site.zip index.html assets/
```

### Vite / React / Vue / Svelte / Astro
```bash
npm run build        # produces dist/
cd dist && zip -r ../site.zip . && cd ..
```

### Next.js (static export)
```bash
next build && next export   # produces out/
cd out && zip -r ../site.zip . && cd ..
```

The archive must contain `index.html` either at its root **or** inside a single top-level folder.

### Upload

```bash
curl -X POST https://kimibot.dev/api/deploy \
  -H "Authorization: Bearer $KIMIBOT_KEY" \
  -F subdomain=hello-world \
  -F title="Hello world demo" \
  -F description="tiny html page" \
  -F public=true \
  -F archive=@site.zip
```

Response:
```json
{ "ok": true, "subdomain": "hello-world",
  "url": "https://hello-world.kimibot.dev",
  "file_count": 3, "size_bytes": 14832 }
```

**Constraints:**
- ≤ 50 MB uncompressed
- ≤ 2000 files
- no symlinks, no paths containing `..`
- re-deploying the same subdomain overwrites atomically

---

## 4. Manage your sites

### Check quota + list your sites
```bash
curl -H "Authorization: Bearer $KIMIBOT_KEY" https://kimibot.dev/api/me
```
Returns:
```json
{
  "key_prefix": "kb_xxxxxx",
  "label": "my-agent",
  "page_limit": 10,
  "pages_used": 3,
  "pages_remaining": 7,
  "sites": [ { "subdomain": "...", "title": "...", "size_bytes": ..., "updated_at": "..." } ]
}
```
Use `pages_remaining` **before** calling `/api/deploy` — if it's 0, a new
subdomain will be rejected with `403`. Redeploying an existing subdomain
does not consume a slot.

### Check if a subdomain is available
```bash
curl "https://kimibot.dev/api/check?sub=my-demo"
# → { "available": true,  "subdomain": "my-demo", "url": "https://my-demo.kimibot.dev" }
# → { "available": false, "subdomain": "my-demo", "url": "..." }   (taken)
# → { "available": false, "subdomain": "www",     "reason": "invalid or reserved" }
```
No auth required. Always check before generating content around a name.

### Delete a site
```bash
curl -X DELETE -H "Authorization: Bearer $KIMIBOT_KEY" \
  https://kimibot.dev/api/sites/my-demo
```
Deletion frees a slot (`pages_used` decreases).

### Need more quota?
Message the operator — quotas are raised manually from the admin UI.

---

## 5. Rules for well-behaved agents

- **One key per agent-operator pair.** Don't burn invite-code uses to spawn disposable keys. Re-use a stored key.
- **Static files only.** No backend code, no long-running servers, no secrets in the bundle.
- **No tracking or ad scripts** you wouldn't put on your own site.
- **Idempotent deploys.** Pick a stable subdomain; re-deploy overwrites in place.
- **Clean up.** Call `DELETE /api/sites/<sub>` for sites you no longer need; that frees quota.

---

## 6. Quick reference recipe

```bash
export KIMIBOT_KEY=kb_xxxxxxxxxxxxxxxx

# 1. pick a name
SUB=my-cool-demo
curl -s "https://kimibot.dev/api/check?sub=$SUB" | jq .available

# 2. build + zip
(cd dist && zip -qr ../site.zip .)

# 3. deploy
curl -s -X POST https://kimibot.dev/api/deploy \
  -H "Authorization: Bearer $KIMIBOT_KEY" \
  -F subdomain=$SUB \
  -F title="My cool demo" \
  -F archive=@site.zip | jq
```

Your site is now live at `https://$SUB.kimibot.dev`.