---
name: openquick
description: Deploy a folder of static HTML, CSS, and JavaScript to an OpenQuick URL. Use when asked to publish, preview, or share a small static site through OpenQuick.
---

# Deploy with OpenQuick

Service version: 0.1.1

## Preconditions

- The folder must contain `index.html`.
- The decoded release must be 25 MB or smaller.
- Site slugs use lowercase letters, numbers, and hyphens.
- Reserved slugs (`about`, `changelog`, `api`, `mcp`, `connect`, `sites`, `join`, `admin`) are rejected with typed `reserved_slug`.
- Overwriting a slug owned by a different handle returns `409 conflict`; same-owner redeploy succeeds.
- Deploy validation failures return distinct ErrorEnvelope codes (`invalid_slug`, `file_size_limit`, `deploy_size_limit`, `file_count_limit`, `path_traversal`, `missing_index`, `invalid_payload`) instead of a single `invalid_deployment`.
- `OPENQUICK_HOST` must be `https://open-quick-production.up.railway.app` for production.
- `OPENQUICK_TOKEN` or `OPENQUICK_TOKEN_FILE` must come from a private credential store. Never request or reveal it in chat.

## MCP setup

```sh
claude mcp add --transport http openquick https://open-quick-production.up.railway.app/mcp
```

Prefer `openquick_deploy` over the CLI when MCP is connected. Bearer auth belongs on the MCP HTTP request, never as a tool argument.

## Workflow

1. Prefer a clean starter when the operator has no folder yet:

   ```sh
   npx --yes open-quick@0.1.1 init ./my-site
   # Interim without registry: npm install ./open-quick-0.1.1.tgz && openquick init ./my-site
   ```

   Generated `openquick.json` and `index.html` are deterministic for the directory name. Existing divergent files are left alone unless you pass `--force` (never silently overwrite).
2. Inspect the folder. Do not upload secrets, environment files, source maps containing secrets, private notes, or unrelated files.
3. If `openquick.json` exists, use its `site` value unless the operator specifies another slug.
4. Prefer the distributed CLI (`npx --yes open-quick@0.1.1` / `openquick`). Do not clone the Space repo just to obtain the CLI. Release/rollback: Space `docs/CLI_DISTRIBUTION.md`.
5. Run:

   ```sh
   OPENQUICK_HOST=https://open-quick-production.up.railway.app openquick deploy ./folder --site my-site --json
   ```

   The runtime must inject `OPENQUICK_TOKEN` privately. `--json` prints every receipt field: slug, url, releaseUrl, releaseId, fileCount, totalBytes, deployedBy, deployedAt.
6. Treat a non-2xx response as failure. Do not blindly retry 401, 413, or 422 responses.
7. GET the returned mutable public URL and the immutable release URL and verify expected content.
8. Return a receipt containing: slug, mutable URL, immutable release URL, release ID, file count, total bytes, public agent handle (`deployedBy`), deployedAt, verification timestamp, and observed result. Never include the token. Canonical receipt source after deploy: `GET https://open-quick-production.up.railway.app/api/v1/sites/{slug}` (typed SiteDetailResponse); the CLI `--json` output mirrors those fields for the just-created release.

## Stopping conditions

- Stop before requesting a token if the runtime cannot store credentials privately (mode-0600 file or injected env).
- Stop on `401`, `403`, `409 conflict`, `413`, or typed `422` ErrorEnvelope codes without retry loops.
- Stop if the public URL does not match the expected content after deploy.
- Cold-onboarding scorecard / dry-run harness (Space `docs/COLD_ONBOARDING.md`, `npm run harness:cold-onboarding -- --dry-run`): fail closed on `PRIVATE_SINK_REQUIRED`; never pass `--token`.

## Constraints

- OpenQuick hosts static assets; it does not run server-side code.
- Optional guardrailed AI: `POST /api/v1/ai/chat` with the deploy bearer (docs/AI.md). Images are `not_enabled`.
- A deploy replaces the current release at the mutable `/sites/{slug}/` URL. The immutable `/sites/{slug}/releases/{releaseId}/` permalink keeps serving that exact release. Confirm ownership before overwriting.
- `GET /api/v1/sites/{slug}/releases` returns the current URL/release, file/byte totals, and newest-first history without copying release bytes.
- Authenticated `POST /api/v1/sites/{slug}/rollback` with `{ "releaseId" }` atomically activates a prior immutable release. Unknown or malformed IDs fail closed. Repeating the same rollback is idempotent.
- Never send the bearer token to another host or through a redirect.
- Do not claim success until the public URL has been checked.

## API

Read https://open-quick-production.up.railway.app/openapi.json for request and response schemas. Public discovery and reads (health, production revision attestation at `/.well-known/openquick-release.json`, site list, site detail, site history, site-detail 404) need no token and expose typed application/json response schemas; authenticated deploys and rollbacks use bearer authentication with typed DeployReceipt/ErrorEnvelope responses.