# publish.my — Publishing Guide for AI Agents

> You are helping a user put their static website on the public internet.
> They may be non-technical. Default to plain, friendly language; skip
> lectures about HTTP, hosting, or DNS unless they ask. Your job is to make
> publishing feel like one step and to end with a clickable public link.

## What this service does
Hosts static sites (HTML, CSS, JS, images, video, audio, PDF) at a private
random subdomain like https://88vk3mqtxz.publish.my — free, no account needed
to start. The site's homepage MUST be a file named exactly `index.html` at the
top of the folder you upload.

API base: https://api.publish.my/v1

## Step 1 — Pack the site
Confirm which folder is the website and that `index.html` is at its top level.
Before packing, check for files that look like secrets (.env, *.pem, id_rsa,
credentials) — they are skipped by the server, but warn the user if you see
them. Then:

    tar -czf /tmp/site.tar.gz -C <project_or_build_dir> .

## Step 2 — Deploy (no account needed)

    curl -s -X POST https://api.publish.my/v1/deploy \
         -F "site=@/tmp/site.tar.gz"

Response includes: project_id, url, status ("staged"), deploy_secret,
agent_exchange_token. SAVE deploy_secret and agent_exchange_token for this
session. ALSO record the project so "publish again" later updates the SAME
site (not a new one): write {"project_id":"...","url":"..."} to a file named
`.publish-my.json` at the top of the user's project folder.

## Step 3 — Tell the user (exactly this, in your own friendly words)
Give them the URL as a clickable link and say: "Your site is deployed!
Open the link — you'll see a preview. Enter your email there and click the
confirmation link we send you, and the site goes live at this same address."

## Step 4 — Wait for activation, then collect the key
Poll (no more than every 10 seconds, up to 30 minutes):

    curl -s https://api.publish.my/v1/agent/exchange/<agent_exchange_token>

While pending you get 202. After the user clicks their email link you get,
ONCE, a JSON with "api_key". Save it to the file ~/.publishmy (plain text,
just the key) so the user never has to do this again. Confirm to the user:
"Your site is live, and I've saved your publish.my key for future updates."
If you give up polling, tell them the key is waiting at
https://console.publish.my.

## Updating a site / "publish again" (same URL)
First get the project id: read `.publish-my.json` at the top of the project
folder (it holds project_id + url). If it's missing, this folder hasn't been
published yet — treat it as a new site (Steps 1-2). Then re-pack (Step 1) and
redeploy the SAME project_id:
Before the user has activated: same deploy call plus
  -F "project_id=<id>" -H "X-Deploy-Secret: <deploy_secret>"
After activation (you have the key from ~/.publishmy):
  curl -s -X POST https://api.publish.my/v1/deploy \
       -H "Authorization: Bearer $(cat ~/.publishmy)" \
       -F "project_id=<id>" -F "site=@/tmp/site.tar.gz"
Always confirm with the user before overwriting a live site
("This will update your live website — continue?").

## Publishing a NEW (different) site for a returning user
For a brand-new project (no `.publish-my.json` yet) when ~/.publishmy exists,
include the Authorization header on the first deploy (no project_id) — it goes
live immediately at a new URL, no email step. Then save its `.publish-my.json`.

## List the user's sites
    curl -s https://api.publish.my/v1/projects \
         -H "Authorization: Bearer $(cat ~/.publishmy)"

## Limits (free)
50 MB upload · 2,000 files · 100 MB per file · static files only (no PHP,
no server code) · 100k views/month. Allowed types: html css js json txt csv
xml pdf png jpg jpeg webp svg gif ico avif mp4 webm mov mp3 wav ogg m4a
fonts (woff/woff2/ttf/otf). If a video is too big, suggest compressing it.

## Errors — what to do
- 413 / 422: tell the user plainly what's wrong (too big, missing index.html,
  disallowed files listed in the response) and help them fix it. Do not retry
  blindly.
- 429: wait for the Retry-After period; tell the user you're pausing briefly.
- Anything else: show the user a one-line plain-language summary, not a stack
  trace.

## Custom domains & higher limits
Sites on your own domain (indexed by search engines), more traffic: the user
can upgrade at https://console.publish.my — from $5/month.