sites-hosting v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/55e0c6e45eaa0247.

---
name: sites-hosting
description: Securely package and publish a validated static dist directory to Sandwalk Sites, then wait for a ready public URL.
author: sandwalk
category: Built-in
version: 1.0.0
---

# Sites Hosting

Publish the exact static output produced by `sites-building`. Use this skill when
the user asks to host, deploy, publish, or update a Sandwalk Site.

## Requirements

- Publish static output only. The input must be the final validated `dist/`, not
  source files, a project root, or a development server.
- `FASTFOLD_API_KEY` is required. Prefer the existing environment or Sandwalk
  Integrations credential. If `sites.manage` reports missing authentication, ask
  the user to configure it; never request, print, or inspect the secret value.
- Use `sites.manage` for all local registration and remote publication operations. Read its current
  action and argument descriptions before each workflow; they are authoritative.
  Do not invent actions, fields, provider APIs, or direct HTTP requests.

## Workflow

1. **Identify the exact output.** Resolve the intended `dist/`. For a changed
   existing site, retain the site identifier returned by `sites.manage`; do not
   silently create a second site.
2. **Package and validate.** Run from this skill's directory:

   ```bash
   python scripts/package_site.py <project>/dist <workspace>/site.zip
   ```

   The script emits one JSON object on stdout. It creates a deterministic archive
   and adjacent manifest, then verifies that both describe exactly the same files.
   Fix every failure; never bypass path, secret, file-count, or 100 MB limits.
   Read [Package contract](references/package-contract.md) when diagnosing a failure.
3. **Choose the address.** Ask for a custom slug only when the user cares about
   the address. Otherwise allow Sites to generate one. A generated slug, or a
   requested custom slug when available, is served at
   `https://<slug>.sandwalk.site`. A requested slug is not reserved until the tool
   confirms it.
4. **Register or update.** Call `sites.manage` with `action="create"` and the
   validated `dist/` path once, or `action="update"` with the retained local site
   identifier after rebuilding. The tool snapshots and independently validates
   the exact directory.
5. **Publish.** After confirming this public side effect with the user, call
   `sites.manage(action="publish", site_id="<id>")`. Pass `slug` only when the
   user requested one. The tool packages, uploads, and waits for the deployment.
6. **Confirm status.** If publication returns without a terminal state, call
   `sites.manage(action="status", site_id="<id>")` until terminal:
   - `published` (or an equivalent success state): publication is durable; report the final URL.
   - `failed`, `cancelled`, or equivalent: report the failure and useful detail.
   - timeout or unknown state: report that publication is still unconfirmed and
     provide the operation/site identifier for follow-up.

   Use reasonable intervals and honor retry hints. Do not republish merely because
   processing is asynchronous. Read [Publishing lifecycle](references/publishing-lifecycle.md)
   for status and communication rules.

## Completion Rules

- Never say deployed, published, live, successful, or ready before status is
  exactly the tool's ready/success terminal state.
- A URL in an accepted or processing response is provisional, not proof of
  success.
- On success, state the final URL and whether the slug was generated or custom.
- On non-ready outcomes, state the observed status, concise reason, and next safe
  action. Never fabricate a URL from a requested slug.
- Keep progress messages factual: packaging, upload accepted, processing, ready,
  or failed. Do not expose credentials, raw authorization errors, or provider
  implementation details.

## Resources

- [Package contract](references/package-contract.md)
- [Publishing lifecycle](references/publishing-lifecycle.md)
- `scripts/package_site.py` — deterministic package, manifest, and exact-output validation