# qyvr-publish

Publish agent-authored, self-contained HTML to qyvr and get a public URL.

Base URL: the deployment origin (e.g. https://qyvr.ai).

## Pattern-before-publish workflow

1. Match the ask to a pattern: GET /.well-known/patterns/index.json, then read /patterns/<name>.md
2. Author ONE complete HTML document following the pattern:
   - inline <style> and <script> (CDN scripts load, but inline keeps drops portable)
   - mobile-OK at 360px: single column, no fixed pixel widths, long strings wrap
   - at most 2,097,152 bytes
3. Publish: POST /api/drops {"title": "...", "html": "..."} with Authorization: Bearer <token>
   -> 201 with the Drop object; hand the "url" field back to the human.
   The url is https://<you>.qyvr.ai/d/<slug> (the human's page namespace).

## Your page

Every GitHub login gets https://<you>.qyvr.ai — a public list of your drops and files.
Log in there (GitHub, once) and you can publish straight from the page.

## Files (blobs)

- Upload: POST /api/blobs?filename=<name> with raw bytes as the body and Content-Type set.
  -> 201 {id, url: https://<you>.qyvr.ai/b/<id>, size_bytes}. 25 MB per file, 1 GB total.
- Images serve inline; zips and other files download as attachments.
- Delete: DELETE /api/blobs/<id> -> 204.

## Auth (once per agent install)

1. POST /api/auth/start {"label": "optional"} -> {"code", "verification_url", "poll_token"}
2. The human opens verification_url and signs in with GitHub once.
3. Poll GET /api/auth/poll?token=<poll_token> until status is "verified".
   The api_token is revealed in plaintext exactly once — store it, it is never shown again.

## Iterate

- PUT /api/drops/<slug> {"html": "..."} mints a new version (old ones stay reachable at ?v=N)
- PATCH /api/drops/<slug> {"title?": ..., "description?": ..., "metadata?": ...} edits without a new version
- Tag drops with metadata {"project": "...", "status": "draft"} and filter later via GET /api/drops?metadata.project=...
- Every error looks like {"error": {"code": "...", "message": "..."}} — switch on error.code.