# SUPRi — agent instructions

SUPRi lets you build and deploy a website from Claude, Codex, ChatGPT, or any AI agent via MCP (or REST).
The end user should not visit https://dev.supri.io. Access is invite-only.

If a human told you "go build this website using supri.io" (dashboard dev.supri.io,
sites on supri.io), you already have everything you need on this page.

## 0. Fastest path

If the owner gave you a URL like https://dev.supri.io/mcp?invite=SPR-XXXX-XXXX-XXXX,
add it as a Streamable HTTP MCP server and you are signed in: no token
handling needed. The invite in the URL is the credential (single-use invites
only; revoking the invite cuts it off). Then: get_site_status or create_site,
edit with write_file, save_version, share the -dev preview link, and
promote_to_production only when the owner says to publish.

Owners who do not use an agent sign in at https://supri.io/login with an
emailed code and edit by chatting with the built-in assistant.

## 1. Discover

- This file: https://dev.supri.io/llms.txt
- Human-readable: https://dev.supri.io/agents
- Same text behind the Access bypass: https://dev.supri.io/api/v1/llms.txt
- MCP (Streamable HTTP): POST https://dev.supri.io/mcp
- MCP manifest (name, endpoint, auth): https://dev.supri.io/.well-known/mcp.json
- REST: https://dev.supri.io/api/v1
- Health: https://dev.supri.io/health

Cloudflare Access may sit in front of the dashboard. These paths bypass it
and use app tokens instead: /mcp*, /api/v1*, /p/*. Prefer those.

## 2. Get access (no prior account)

Call the public tool. No Authorization header.

MCP JSON-RPC:

  POST https://dev.supri.io/mcp
  Content-Type: application/json

  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"your-agent","version":"1"}}}
  {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"redeem_invite","arguments":{"code":"SPR-XXXX-XXXX-XXXX","email":"client@example.com","site_name":"Northline Plumbing"}}}

REST equivalent (also unauthenticated, rate-limited):

  POST https://dev.supri.io/api/v1/redeem
  {"code":"SPR-XXXX-XXXX-XXXX","email":"client@example.com","site_name":"Northline Plumbing"}

Response includes:
- token (spr_acct_…) — save it; it is shown once
- site.url when site_name was provided
- mcp_url

Ask the owner for the invite code if they did not paste it. Do not send
them to the dashboard.

## 3. Authenticate

Every later request:

  Authorization: Bearer spr_acct_…

OpenAI Codex MCP config:

  {
    "mcpServers": {
      "supri": {
        "url": "https://dev.supri.io/mcp",
        "headers": { "Authorization": "Bearer spr_acct_YOUR_TOKEN" }
      }
    }
  }

Claude Code:

  claude mcp add --transport http supri https://dev.supri.io/mcp \
    --header "Authorization: Bearer spr_acct_YOUR_TOKEN"

Grok Build and other Streamable HTTP clients: same URL and bearer header.

## 4. Build the site

Account-token tools:
- create_site({name, slug?}) — starter template, live immediately, private by default
- list_sites()
- get_site_status({site_id?}) — includes the live URL and visibility
- set_site_visibility({visibility:"public"|"private"}) — new sites start private

Site tools. There are three places a site lives:
  draft       your working copy; every write_file/delete_file lands here
  preview     https://<slug>-dev.supri.io/ always shows the draft (owner-only login, never public)
  production  https://<slug>.supri.io/ serves ONE saved version (public or private per set_site_visibility)

- list_files, read_file, write_file, delete_file   (edit the draft)
- preview()  temporary share link for the draft, 24 hours, no login
- save_version({message?})  snapshot the draft as v<N> (author + timestamp recorded); production unchanged
- list_versions()  newest first, with is_production, production_url, preview_url
- get_version({version_id})  files + diff summary (added/removed/changed) vs the previous version
- promote_to_production({version_id?, message?})  make a version live; with no version_id it saves the draft first
- rollback_to_version({version_id})  promote an older version; the draft is NOT touched
- publish({message?})  shortcut = promote_to_production with no version_id
- rollback({version_id})  legacy: promote AND overwrite the draft

Workflow (edit → preview → promote):
1. get_site_status → note url (production) and preview_url (-dev).
2. read_file, then write_file the smallest change.
3. Tell the owner to check preview_url (they sign in once), or give them a preview() link.
4. save_version({message:"what changed"}) when it looks right.
5. promote_to_production({version_id}) when the owner says go live.
6. If production breaks: list_versions → rollback_to_version({version_id of the last good one}).

REST (same token):

  GET    https://dev.supri.io/api/v1/sites
  POST   https://dev.supri.io/api/v1/sites           {"name","slug?"}
  GET    https://dev.supri.io/api/v1/status
  GET    https://dev.supri.io/api/v1/files
  GET    https://dev.supri.io/api/v1/files?path=index.html
  PUT    https://dev.supri.io/api/v1/files           {"path","content"}
  DELETE https://dev.supri.io/api/v1/files?path=about.html
  POST   https://dev.supri.io/api/v1/preview
  POST   https://dev.supri.io/api/v1/publish         {"message"}
  GET    https://dev.supri.io/api/v1/versions
  POST   https://dev.supri.io/api/v1/versions        {"message"}          save_version
  GET    https://dev.supri.io/api/v1/versions/<id>                      get_version
  POST   https://dev.supri.io/api/v1/promote         {"version_id"?}     promote_to_production
  POST   https://dev.supri.io/api/v1/rollback_to_version {"version_id"}
  POST   https://dev.supri.io/api/v1/rollback        {"version_id"}      (legacy)
  POST   https://dev.supri.io/api/v1/visibility      {"visibility":"public"}

Rules:
- Read before you write. Smallest change that satisfies the owner.
- Preview (the -dev host) before promoting unless they clearly said to go live.
- Never promote without the owner's go-ahead unless they asked you to ship directly.
- write_file replaces the whole file.

## 5. URLs

Production (after promote/publish; create_site promotes the starter as v1):

  https://<slug>.supri.io/

Draft preview (owner sign-in, always private, noindex):

  https://<slug>-dev.supri.io/

Slugs cannot end in -dev.

The dashboard stays on dev.supri.io. Client sites use SITES_HOST (supri.io).

Examples:
- SITES_HOST=supri.io, APEX_HOST=dev.supri.io → https://northline.supri.io/
- localhost                                   → https://dev.supri.io/s/<slug>/

New sites are private. The owner (or an admin) must sign in on the dashboard
to view them, or call set_site_visibility({visibility:"public"}). Preview
URLs (/p/…) keep working. Existing sites created before this change stay public.

Custom domains are not in this phase.

## 6. What you must not do

- Do not ask the owner to create an account on the website.
- Do not treat an invite or site token as admin. Admin is a dashboard role
  for tim528@gmail.com only, via Cloudflare Access.
- Do not put tokens in git or wrangler.jsonc.

Invite codes are created by an admin. If redeem_invite fails, the code is
wrong, expired, revoked, or used up — ask the owner for a fresh one.