Plugin & skills

---
name: connect
description: Connect this AI to snaphost over MCP and verify it can manage your sites.
---

Connect this AI client to snaphost over MCP so it can publish, update, and share the user's
sites. Goal: **one browser click, no token in chat, no copy-paste.** Drive it as a single clear
step at a time, and never hand the user a list of actions to do at once.

## Talking to the user (follow exactly)

- **One step at a time.** Say the single next thing to do, then stop and wait.
- **Make links clickable.** Put any authorization URL on its **own line, raw**: just the
  `https://…` with nothing else on the line (no markdown link syntax, backticks, or trailing
  punctuation). That is what renders as a clickable link.
- **One live link only.** Each new authorization attempt invalidates the previous link. Show only
  the newest URL and tell the user to ignore any earlier ones.
- **Restarts, in plain words.** A newly added MCP server loads only when Claude restarts. When that
  is needed, say it exactly like this: *"Fully quit Claude and reopen it (a reload is not enough),
  then tell me you're back."* Then stop and wait.
- **Never** ask the user to paste a secret or API token into the chat.

## Steps

1. Call `list_sites`. If it returns anything (even an empty list), you are already connected;
   go to step 4.
2. If snaphost's tools are not available at all, the server is not registered yet. Add it at user
   scope (so it works in every project), then have the user fully quit and reopen Claude:

   ```bash
   claude mcp add --transport http snaphost https://app.snaphost.ai/api/mcp -s user
   ```

3. Once the server is loaded, start the browser flow. When the client surfaces an authorization
   URL, present it as one step: put the raw `https://…` URL on its own line and tell the user to
   **click Authorize** (they choose how long the connection lasts, including *Never expires*). The
   credential is then negotiated machine-to-machine; no token ever enters the chat.
4. Confirm with `list_sites`. An empty list means it works (no sites yet); offer
   `/snaphost:publish`. A populated list means you're connected. Tell the user they're ready.

## If the Authorize page errors

The redirect lands on a `http://localhost` address handled by Claude Code itself (not snaphost),
so a "this site can't be reached" page is usually a loopback IPv4/IPv6 mismatch or a timed-out
listener, not a snaphost failure. Recover in order:

1. Have the user fully quit and reopen Claude, then click the fresh link **promptly**; these links
   expire within a minute or two.
2. If it still errors, the URL now in their address bar
   (`http://localhost:<port>/callback?code=…&state=…`) is still valid; ask them to paste that one
   URL so the client can finish. It is a single-use code, not a reusable secret.

## Token fallback (last resort, only if the browser flow is truly unavailable)

The user creates an API token in the dashboard under **API tokens** (shown once) and runs this in
*their own* terminal, replacing `<token>`, so the secret stays in their shell, never in this chat:

```bash
claude mcp add --transport http snaphost https://app.snaphost.ai/api/mcp --header "Authorization: Bearer <token>" -s user
```

`-s user` stores it in the user's own Claude config; never echo, write, or commit it.

## Notes

- The hosted endpoint is `https://app.snaphost.ai/api/mcp`. Any client that supports HTTP (Streamable) MCP with
  OAuth works: point it at that URL and approve the browser prompt.
- After setup the credential lives on the MCP connection; `/snaphost:publish`,
  `/snaphost:update`, and `/snaphost:share` never ask for it again.

---
name: workspace
description: Pick which snaphost workspace (team or personal account) to work in, then create or choose a site.
---

Use this skill to choose which snaphost workspace you are working in, then create a new site or
pick an existing one to work on. A workspace is either the token owner's personal account or a
team they belong to.

## Steps

1. Call `list_workspaces`. It returns the workspaces this token can act in (the owner's personal
   account plus any teams they belong to), each with a `workspace_id`, a `handle`, and your
   `role` (owner, admin, or member).
2. If there is more than one, show them to the user and ask which to work in. Remember the chosen
   `workspace_id` and pass it as `workspace_id` on every following tool call (`list_sites`,
   `publish_site`, `update_site`, `set_visibility`, and so on). If there is only one, use it
   without asking.
3. Call `list_sites` with the chosen `workspace_id` and show the user the site titles.
4. Ask what they want to do:
   - **Create a new site** → use `/snaphost:publish` (pass the same `workspace_id`).
   - **Work on an existing one** → confirm which title, then use `/snaphost:update` with its site
     id (and the same `workspace_id`), or `/snaphost:share` to change who can view it.
   - **Add a data feature** (contact form, waitlist, RSVP, guestbook, counter, clock-in, leaderboard) → use
     `/snaphost:data` to give a site a backend it can save and read data from.

## Notes

- Always carry the chosen `workspace_id` through the rest of the session so work lands in the
  right account. Omit it and every tool acts in the token owner's personal account.
- You can only act in workspaces `list_workspaces` returns; a `forbidden` error for another id
  means the token owner is not a member of it.
- Re-run this skill any time to switch workspaces.

---
name: publish
description: Publish the current document to snaphost as a live, shareable site.
---

Use this skill to publish something the user just built (an HTML file, a report, a
notebook, a bundle) to snaphost as a live site with a stable, shareable link.

## Steps

1. Identify the document to publish. If it is a single self-contained HTML file, read it.
   If it is a folder/bundle, zip it (entry document at the root, e.g. `index.html`).
2. Choose a stable, human `slug` derived from the title (e.g. "Q3 Investor Update" →
   `q3-investor-update`). The slug makes publishing idempotent.
3. Call `publish_site` with a `title`, the `slug`, and the bundle. For a single document use
   `html`; for a small zip use `zipBase64`. For a large or multi-file app (a built Vite/React
   site, an image-heavy page) call `create_bundle_upload` first, PUT the .zip to the returned
   `url` (HTTP PUT, `Content-Type: application/zip`), then pass that `upload_id` instead; this
   bypasses the request-body size limit, so size is not a concern.
4. Report the returned `share_url` to the user. Tell them the link is stable: re-running
   this skill with the same slug updates the same site in place, and viewers see it live.

## Notes

- New sites default to private (allowlist) on paid plans. Use `/snaphost:share` to open it
  up or add viewers.
- To change an existing site instead of creating a new one, use `/snaphost:update`.
- A multi-file app gets client-side routing for free: clean routes like `/about` deep-link
  and survive a refresh. Build with `BrowserRouter` and a relative base (`base: './'`), and
  derive the router basename from the injected `<base>` tag (`document.querySelector('base')`).

---
name: update
description: Update an existing snaphost site in place, keeping its URL.
---

Use this skill to change the content of an existing snaphost site without changing its
URL, visibility, or allowlist.

## Steps

1. Determine the target site. If the user gave a site id, use it. Otherwise call
   `list_sites` and match by title, confirming the right one with the user if ambiguous.
2. Fetch the current content with `get_site_content` (the site id). It returns the entry
   document: `content` as UTF-8 text for HTML/Markdown, or base64 for binary, with
   `encoding` telling you which.
3. Apply the user's requested change to that content. Edit the real current document; do
   not regenerate it from scratch, so wording, structure, and styling are preserved.
4. Save with `update_site` (the site id) passing the edited bundle: `html` (a single
   document), `zipBase64` (a small bundle), or, for a large or multi-file rebuild, an
   `upload_id` from `create_bundle_upload` (PUT the .zip to its `url` first).
5. Confirm: the share URL is unchanged and anyone viewing it refreshes to the new version
   automatically. Mention you can roll back via `list_versions` + `rollback_site`.

## Notes

- `get_site_content` is the read half of the round-trip; always read before you write so
  you patch the live document rather than overwrite it blindly.
- The token is configured on the MCP connection; never request or paste it.

---
name: share
description: Control who can view a snaphost site: visibility, allowlist, password, and link expiry.
---

Use this skill to manage who can view a snaphost site and how the link behaves.

## Steps

1. Identify the site (a site id, or resolve by title with `list_sites`).
2. Apply the change the user asked for:
   - **Public vs private**: `set_visibility` with `public` (anyone with the link) or
     `allowlist` (verified viewers only).
   - **Share with more people**: `add_to_allowlist` adds emails and/or domains *without*
     removing anyone already on the list; this is the default for "share with X". Check who is
     already on it first with `list_allowlist` (or `get_site`). Use `remove_from_allowlist`
     to take specific people off, and only reach for `set_allowlist` when the user explicitly
     wants to replace the whole list (it overwrites everyone; an empty list clears it).
   - **Password**: `set_view_password` to protect it, `clear_view_password` to remove it.
   - **Expiry**: `set_link_expiry` with an ISO 8601 timestamp, or null to clear.
3. For private sites, manage pending requests with `list_access_requests` and then
   `approve_access_request` / `deny_access_request`.

## Notes

- Private sharing, allowlists, and passwords are paid-plan features; if a call returns a
  `plan_limit` error, tell the user which plan unlocks it.
- Visibility, allowlist, and password changes never change the share URL.

---
name: data
description: Add a data feature (contact form, waitlist, RSVP, guestbook, counter, leaderboard) to a snaphost site so the published page can save and read data.
---

Use this skill to give a snaphost site a backend: the published page persists and reads data
through the injected `window.SNAPHOST` SDK, with no server to run. snaphost Data is a Premium/Team
feature; a `plan_limit` error means the owner needs to upgrade.

## Adding a ready-made feature (the fast path)

1. Identify the site (a site id, or resolve by title with `list_sites`).
2. List the templates with `list_data_recipes` (contact form, waitlist/email signup, RSVP,
   guestbook, shared counter, clock-in, leaderboard). Pick the one matching what the user asked for.
3. Call `apply_data_template` with the site id and recipe id. It provisions the collection (its
   access mode and schema) and **returns an HTML snippet**.
4. Add that HTML to the user's page: fetch the current document with `get_site_content`, merge the
   snippet into the right place (do not regenerate the page from scratch), then `update_site`.
   Confirm the change is live.

## Building something custom

The injected SDK is global and needs no keys; every call returns a promise.

- **Append**: `await window.SNAPHOST.append('<collection>', { ...yourFields })`. The collection is
  created on first write; never create it first. Records are immutable and append-only; an "edit" is
  a new event carrying the same `key` field.
- **Read**: `const { records } = await window.SNAPHOST.query('<collection>', { order: 'desc', limit: 50 })`.
  Each record is `{ id, value, created, actor }`: read the owner's fields from `record.value` and
  the timestamp from `record.created`. Query options: `order` ('asc' | 'desc'), `limit`,
  `where: [{ field, value }]` (equality filters), and `latest: true` to fold to the newest record
  per `key` (current state instead of full history).
- **Who is viewing**: `const me = await window.SNAPHOST.viewer()` resolves (after `ready`) to the
  current viewer's identity. A signed-in viewer of a private / allowlist site gives
  `{ id: 'user@example.com', kind: 'viewer' }`; a public site or a password-only viewer gives
  `{ kind: 'anonymous' }` (no `id`). `viewer` shows up in `Object.keys(window.SNAPHOST)`.
- **Read config (key-value)**: `await window.SNAPHOST.get('<namespace>', '<key>')` and
  `await window.SNAPHOST.list('<namespace>')` read owner-set values (set via `set_site_data`).
- **Render safely**: write values with `textContent`, never `innerHTML`.
- **Access mode** (`set_collection_access`): `public_read` (anyone can read: a guestbook or
  counter) or `append_only` (visitors write but only the owner reads: a contact form or
  waitlist; submissions are never readable by other visitors). You can also pause writes.
  Publish/update scans the page's code and pre-configures new collections to match it (one the
  page `query()`s becomes `public_read`, one it only `append()`s to stays `append_only`) and
  reports what it did in the tool result; an owner's explicit setting is never overridden.
- **Schema** (`define_collection_schema`): an optional JSON Schema validates every appended record
  server-side. Set it for the user when their data has a fixed shape.
- **Inspect / moderate**: `list_site_collections`, `query_site_records`, `export_site_data`,
  `delete_site_record`. Attribution on each record is server-stamped from the verified viewer on a
  private site, never from the request body. Note: collections are per-site, so a page only sees its
  own site's collections.

## Attributing a record to a person ("who did this")

For any feature that shows who did something (leaderboard, high scores, guestbook, comments,
clock-in, RSVP): capture the viewer with `window.SNAPHOST.viewer()` and **write the identity into
the record's `value`** (a `who` field). `actor` is server-stamped and visible to the owner in the
dashboard and exports, but it is **redacted in-page** (only `kind`, never the id), so never read
`actor` back to display who wrote a record, and never fall back to `window.prompt()` for a name.

**Aggregation rule** for a per-person board: records that HAVE an identity fold to that person's
best (or latest) row; records with NO identity are anonymous and must each stay their own row,
never merged into a single "Anonymous". Worked snippet (capture -> stamp -> aggregate, top N):

```html
<script>
  let me = { kind: 'anonymous' }
  window.SNAPHOST.viewer().then(v => { me = v })

  async function submitScore(score) {
    const entry = { score }
    if (me.kind === 'viewer' && me.id) entry.who = me.id // stamp identity into the value
    await window.SNAPHOST.append('leaderboard', entry)
    render()
  }

  async function render() {
    const { records } = await window.SNAPHOST.query('leaderboard', { order: 'desc', limit: 500 })
    const best = new Map(), anonymous = []
    for (const r of records) {
      const who = (r.value.who || '').trim()          // never read r.actor here (redacted in-page)
      const score = Number(r.value.score) || 0
      if (!who) { anonymous.push({ label: 'Anonymous', score }); continue }
      const key = who.toLowerCase(), prior = best.get(key)
      if (!prior || score > prior.score) best.set(key, { label: who, score })
    }
    const rows = [...best.values(), ...anonymous].sort((a, b) => b.score - a.score).slice(0, 10)
    const list = document.getElementById('leaderboard')
    list.replaceChildren()
    for (const row of rows) {
      const li = document.createElement('li')
      li.textContent = row.label + ': ' + row.score // textContent, never innerHTML
      list.appendChild(li)
    }
  }
</script>
```

## Notes

- Recommend the ready-made templates first; they are the simplest path for a non-technical owner.
- Always re-publish (`update_site`) after adding a snippet, or the feature will not be live.