# agenthost — publish a static site or docs, get a private share link. Invite-only.

## Account (once, done by the human)
Publishing is invite-only. The operator invites the human by email. The human
signs in at https://account.ossystems.link, generates an agent token, and gives you
the token and their username. A publish without the token returns 401.

## Publish (one command, zero install)
# A single .md or .html — pipe it straight in (md renders, html is served as-is;
# the file lands at the site root /):
curl -s --data-binary @report.md \
  -H 'Authorization: Bearer <ownerToken>' \
  'https://ossystems.link/publish?id=report&username=<username>'

# A whole folder — pipe a tar of it:
tar cf - -C ./dist . | curl -s --data-binary @- \
  -H 'Authorization: Bearer <ownerToken>' \
  'https://ossystems.link/publish?id=myblog&username=<username>'

## Response (JSON)
{
  "shareUrl": "https://cleverotter4f2-myblog.ossystems.link/?k=<key>",  // hand THIS to a human; private + pre-authed
  "url": "https://cleverotter4f2-myblog.ossystems.link/",              // bare URL (prompts for the key)
  "accessKey": "<the site access key, also embedded in shareUrl>",
  "username": "cleverotter4f2"                                           // your account name (auto-generated, no hyphens)
}

Publishing again with the same id replaces the content at the same URL.

## Large downloadable assets
Three calls, all with -H 'Authorization: Bearer <ownerToken>' except the PUT:
1. POST https://ossystems.link/asset?username=<username> with JSON
   {"name":"demo.mp4","bytes":<exact size>,"contentType":"video/mp4"}
   → uploadUrl, uploadHeaders, completeUrl, shareUrl (the shareUrl only comes back here)
2. curl --upload-file demo.mp4 -H '<each uploadHeaders entry>' '<uploadUrl>'   (within 15 min)
3. POST <completeUrl> → {"ok":true}
The file goes straight from the client to R2. Opening the shareUrl shows a Download
button whose bytes also come directly from R2.
Free max: 100 MB per asset. Paid max: 5 GB per asset.

## Site asset paths
Each site is the root of its own subdomain ({username}-{id}.ossystems.link), so
both absolute and relative asset paths work:
  <link href="/css/app.css">     GOOD
  <link href="./css/app.css">    GOOD

## Notes
- Static sites, markdown docs, OR direct-R2 downloadable assets. /index.html is the default doc; a folder of .md renders as a
  GitBook-style docs site (sidebar + README.md as home; optional SUMMARY.md for ordering and nesting).
- No Content-Type needed: a tar body is a folder, anything else is one document. To publish a
  single file of any other type, add ?file=<name>.
- Sites are PRIVATE by default. Share the shareUrl; visitors stay logged in via a cookie.
  Every page has a "Share" button that copies a key-embedded link.
- Limits (free): 50 files, 5 MB/file, 250 MB/site, 500 MB/account. Hosted sites are noindex.
- Free sites are deleted 15 days after the last publish — redeploy to keep alive.

## Install as a skill (optional — persist this contract)
This publish contract ships as an Agent Skill (SKILL.md + references), so you don't
have to re-read this file on every run. Install it once and it's always in reach.
- Any agent: fetch the skill from https://ossystems.link and load its SKILL.md.
- From source: https://github.com/ceifa/agenthost/tree/main/skills/agenthost
- OpenClaw: openclaw skills install @ceifa/agenthost
- skills.sh: npx skills add ceifa/agenthost --skill agenthost
- Hermes: hermes skills tap add ceifa/agenthost