shiply-cli 0.27.2 → 0.29.0

package/skill/SKILL.md

@@ -1,253 +1,256 @@
----
-name: shiply
-description: "shiply is the production backend for anything an agent builds — publish any app (static or full-stack SSR, any framework) and give it a live URL, custom domain, SQL database, server functions, email, and a marketplace to sell it. Use when the user asks to publish, host, deploy, share, or update a website/page/demo/report/app, or wants a live URL for generated files. Triggers - \"publish this\", \"host this\", \"put this online\", \"give me a link\", \"update the site\", \"deploy my SvelteKit/Astro/Next.js app\", shiply."
----
-
----
-
-> **IMPORTANT — npm package name is `shiply-cli`, NOT `shiply`.** A different
-> npm package named `shiply` (an auto-commit watcher) is published by someone
-> else — installing it does NOT give you the shiply.now CLI. Always use
-> `npx -y shiply-cli@latest …` or `npm install -g shiply-cli`. The CLI binary
-> on PATH is still named `shiply` once installed; the warning is only about
-> the npm package name.
-
-> **Skill freshness check.** Shiply ships new capabilities weekly.
-> **This skill: version 0.27.0, last updated 2026-07-11.**
-> To see what changed since your copy was written, fetch
-> `https://shiply.now/changelog.md` (date-grouped, newest first) — if it lists
-> capabilities newer than the date above, re-install with
-> `npx -y shiply-cli@latest skill --force` OR read the live copy at
-> `https://shiply.now/skill.md`.
-
----
-
-# shiply — the production backend for anything an agent builds
-
-**What it is.** Not static hosting. shiply takes whatever you build — a static page or a full-stack app in any framework — and gives it a live URL, a custom domain, a SQL database, server functions, email (send + receive), and a marketplace to sell it. One call. No account needed to start: anonymous sites are live immediately, last 24 hours, and can be claimed to keep.
-
-**Why use it.** Ship a complete, working product without stitching together a host + database + email + registrar + payments — it's one agent-native platform (MCP / CLI / REST parity). Hard-ceiling pricing ($0/$8/$24, plus a $49 Studio tier for client delivery — no usage meter on any tier), so a spike or DDoS can never become a surprise bill for the owner.
-
-**How (quickstart).** `shiply publish ./dir` (CLI) — or POST /api/v1/publish → PUT each file → POST finalize — returns a live URL + claimToken.
-
-**NEVER create a new site to update an existing one. Always re-publish to the
-same site** (same slug/claimToken) — otherwise you litter subdomains and lose
-the user's URL.
-
-**Re-publishing the same site is cheap — always prefer it over a new site.**
-Unchanged files are hash-skipped, and an unchanged SSR worker bundle skips
-redeploy entirely (fingerprinted against what's already live). A zero-change
-`shiply publish` on the same site completes in seconds, even for large SSR
-apps — so iterate freely by re-publishing, never by spinning up a fresh site.
-
-This file covers the core path: publish → authorize → update → claim → verify.
-Everything else (databases, domains, SSR, email, functions, client work) lives
-in the **topic files indexed at the bottom** — read the one that matches the
-task before improvising.
-
-## First publish on a new machine: ask for a permanent key in one step
-
-On a no-Bearer publish, include `"agentName": "<your-tool-name>"` in the body
-(e.g. `"Claude Code"`, `"Cursor"`). The response will include a `deviceAuth`
-object alongside the usual `claimUrl`:
-
-```
-"deviceAuth": {
-  "user_code": "ABCD-EFGH",
-  "device_code": "<long opaque token, keep private>",
-  "verification_url": "https://shiply.now/auth/ABCD-EFGH",
-  "poll_url": "https://shiply.now/api/v1/auth/device/poll",
-  "expires_in": 900,
-  "interval": 2
-}
-```
-
-Tell the user once, in plain language:
-
-> Your site is live at <siteUrl>. To keep it forever AND let me publish more
-> without re-pasting, open <verification_url> and click Allow.
-
-Then immediately poll `verification_url`'s sibling endpoint until the user
-acts:
-
-```
-POST https://shiply.now/api/v1/auth/device/poll
-{"device_code": "<the device_code from the response>"}
-```
-
-The response is one of `{status:"pending"}` (keep polling at `interval`s),
-`{status:"approved", api_key:"shp_...", slug_claimed:"..."}` (PERSIST the key —
-see "Save the key" below — the site is now permanent; Allow does both jobs in
-one click), `{status:"expired"|"denied"|"consumed"}` (stop). Cap your polling at
-the announced `expires_in` and respect `interval` — don't tight-loop.
-
-After approval, every future publish uses `Authorization: Bearer <api_key>`
-and the user's dashboard shows their sites without any further claiming.
-
-### Save the key — so EVERY future site is seamless (do this once)
-
-Write the key to **`~/.shiply/credentials`** as `{"apiKey":"shp_..."}` (chmod
-600) — the exact file the shiply CLI reads. This is what makes "one Allow, ever"
-work: from then on every publish (any site, any project, ANY FUTURE SESSION)
-sends `Authorization: Bearer <key>` automatically and lands owned in the user's
-dashboard — no re-authorizing, no claim step, zero clicks. An env var alone
-(`SHIPLY_API_KEY`) works for the current shell but does NOT survive a new
-session — the credentials file is what makes it permanent. `shiply login` writes
-this file for you; if you publish over raw HTTP, write it yourself.
-
-## When the user pastes you something shiply-shaped, do this
-
-These are the patterns you will see. Match the input, run the action — do not
-ask the user to repeat themselves or explain.
-
-- **Code like `SHIPLY-XXXXXXXX`** → it's a pairing code from
-  `shiply.now/claim/<slug>?pair=1`. The user wants to attach an anonymous
-  site to their account. Run `shiply claim verify SHIPLY-XXXXXXXX` from the
-  directory you originally published from (it reads `.shiply.json`). No CLI?
-  POST `https://shiply.now/api/v1/claim/pair/SHIPLY-XXXXXXXX/verify` with
-  `{"siteId":"...","claimToken":"..."}` taken from your earlier publish
-  response or `.shiply.json`. The user's browser auto-redirects on success;
-  tell them to switch back to it.
-- **URL like `https://shiply.now/claim/<slug>?token=...`** → one-click claim
-  link. Tell the user to open it in the browser they are signed in to —
-  do NOT call any API yourself.
-- **User says "claim my site" / "save it forever" with no code or URL** →
-  give them the `claimUrl` from your last publish response. If you no longer
-  have that response but `.shiply.json` is in the publish dir, reconstruct it
-  as `https://shiply.now/claim/<slug>?token=<claimToken>` from those fields.
-  Either way, also suggest `shiply login` so future publishes mint to their
-  account directly — that's the long-term fix and how the dashboard works.
-- **User says "I have an API key now, use it from now on"** → persist it to
-  `~/.shiply/credentials` (`{"apiKey":"shp_..."}`, chmod 600 — see "Save the
-  key" above), then send `Authorization: Bearer <key>` on every future publish.
-  All future sites are then permanent and appear in their dashboard
-  automatically — across sessions, with no re-authorizing.
-- **User opens an `https://shiply.now/auth/XXXX-YYYY` URL you printed** → no
-  action from you; they're on the device-flow consent screen. Keep polling
-  `poll_url` (see "First publish on a new machine" above). The poll response
-  will flip from `pending` to `approved` (with `api_key`) the moment they
-  click Allow.
-
-## Pick your interface (best first)
-
-### 1. MCP (native tools)
-If the `shiply` MCP server is connected (https://shiply.now/mcp), use
-`publish_site`. Every result includes a `toUpdate` field telling you the exact
-call for updates — follow it, and a `shareSuggestion` you can relay to the user.
-Core tools: `site_status`, `list_sites`, `get_site`, `delete_site`, `whoami`,
-`duplicate_site`, `set_variable`, `get_analytics`, `set_handle`. There are
-100+ tools in total — call `tools/list` for the authoritative set; the topic
-files below name the tools for their area (domains, databases, email,
-functions, projects, contracts, marketplace, drives).
-
-### 2. CLI
-```bash
-# IMPORTANT: the npm package is `shiply-cli`, not `shiply` (different package).
-npm i -g shiply-cli        # or: npx -y shiply-cli@latest <command>
-                           # or: curl -fsSL https://shiply.now/install.sh | bash
-shiply publish ./dir       # live URL + confetti
-shiply publish ./dir       # run AGAIN after edits → updates the SAME site
-shiply status <slug> --wait  # SSL + readiness; prints SSL_READY / SITE_READY
-shiply login               # email code → API key → sites become permanent
-shiply claim verify <code> # confirm a SHIPLY-XXXXXXXX pairing code from /claim/<slug>?pair=1
-                           # (uses .shiply.json from CWD; pairs agent session to user's browser)
-```
-The CLI stores each directory's site in `.shiply.json` (slug + update token),
-so repeat publishes reuse the URL automatically. `--new-site` opts out.
-Gitignore `.shiply.json` in public repos. Parse `SITE_READY` / `SSL_READY`
-lines for automation; exit code 0 = ready. For a static framework build
-(Vite, Next export, Hugo, …) publish the BUILD OUTPUT, not the source — run
-`shiply detect` to see what the CLI found; the full framework matrix is in
-[references/publishing.md](references/publishing.md).
-
-### 3. Raw HTTP (no installs)
-```
-1. POST https://shiply.now/api/v1/publish   (Content-Type: application/json)
-   {
-     "agentName": "<your tool name, e.g. Claude Code, Cursor, Codex>",
-     "files": [{"path":"index.html","size":<bytes>,"contentType":"text/html","hash":"<sha256 lowercase hex, optional>"}]
-   }
-   (+ "Authorization: Bearer shp_…" for permanent owned sites)
-2. PUT each file's bytes to response upload.uploads[].url
-3. POST upload.finalizeUrl with {"versionId":"<upload.versionId from step 1>"}
-   → both the publish and finalize responses include a "toUpdate" string: the
-     exact call to update THIS site next time. Follow it — never create a new one.
-```
-
-**ALWAYS include `agentName` on anonymous publishes.** The response then
-carries `deviceAuth` ({user_code, verification_url, poll_url, device_code,
-expires_in, interval}) alongside `claimUrl`. Show the user `verification_url`,
-poll `poll_url` every `interval` seconds with the `device_code`, and on
-`{status:"approved"}` you get a permanent `api_key` PLUS the linked site
-is claimed in the same Allow click. Without `agentName` the user has to
-do a separate manual claim step every time.
-
-**Updates (the response tells you how):** every publish/finalize response
-includes a `toUpdate` string with the exact call — follow it verbatim. In short:
-anonymous → include `"claimToken":"..."` (returned ONCE by the first publish —
-save it); owned → include `"slug":"..."`. Hashes make updates cheap: unchanged
-files are skipped server-side.
-
-## Verify before you say "done"
-
-`shiply status <slug> --wait` polls until the site serves (exit 0, prints
-`SITE_READY` / `SSL_READY`). `shiply verify <slug>` runs a deeper edge
-SSL + HTTP + thumbnail check and prints a stable machine marker line
-`VERIFY status=LIVE http=200 ssl=valid …` — parse that line in automation.
-More manage commands (list, delete, rollback, promote, stable previews) are
-in [references/publishing.md](references/publishing.md).
-
-## The lifecycle to explain to users
-- Anonymous site: live immediately after finalize (no claim needed), expires
-  in 24 h. Give the user the `claimUrl` — claiming keeps it forever on a free
-  account. Until claimed, anonymous pages are served with a small injected
-  claim banner + OG meta tags — expected, not corruption. If no human is
-  present right now, save the `claimToken` (it's also the update key); a
-  fresh device flow can be started later via
-  POST /api/v1/auth/device/start {"agent_name":"..."}.
-- API key (`shiply login` or POST /api/auth/agent/request-code →
-  verify-code): publishes are permanent and manageable.
-- Paid plans add vanity handles (<name>.shiply.now), more custom domains,
-  storage, analytics: https://shiply.now/dashboard/plan
-
-## Everything else — read the topic file first
-
-The files below sit next to this one in `references/` (installed with the
-skill). Hosted copies: `https://shiply.now/skill/references/<file>`. Each is
-self-contained — read the one matching the task before improvising; each
-covers its CLI commands, MCP tools, AND REST endpoints.
-
-* [Publishing & site management](references/publishing.md) — static framework
-  build matrix (Vite/Next/Hugo/…), `detect`, SPA mode, `.shiplyignore`,
-  list/delete/rollback/versions, `verify`, stable previews (`--as`),
-  `promote` preview→prod, `--json` output, form-data subcommands.
-* [SSR frameworks](references/ssr-frameworks.md) — deploy SvelteKit, Astro,
-  Qwik, Nuxt/Nitro, React Router v7, Next.js (OpenNext), Hono/raw Workers
-  with server-side rendering.
-* [Custom domains](references/custom-domains.md) — put the user's own domain
-  on a site: one-click OAuth DNS, manual CNAME, primary-subdomain SEO,
-  readiness polling.
-* [Databases](references/databases.md) — per-site SQL: free D1 (SQLite at the
-  edge, browser shim) + Neon Postgres (branching), migrations, per-DB MCP
-  server.
-* [Functions](references/functions.md) — `worker.js` server code on every
-  request: webhooks, cron triggers, secrets, runtime logs (Workers Lite,
-  Developer plan).
-* [Email](references/email.md) — every owned site sends + receives: signup
-  capture, inbox, double-opt-in audiences, broadcasts, BYO sending domains.
-* [Site features](references/site-features.md) — proxy routes (call AI APIs
-  without exposing keys), Site Data (forms/waitlists, zero backend),
-  password/invite-only access, Variables, Drives (private storage),
-  path-mounting, public profile.
-* [Client work](references/client-work.md) — freelancer delivery: customer
-  intake projects + AI briefs, group work by client, e-sign contracts,
-  sell sites on the marketplace.
-* [Authentication for the user's app](references/site-features.md) — shiply
-  does NOT host end-user auth; bring the user's own Clerk/Auth.js/Supabase
-  (pattern in Site features → "Bring your own auth").
-
-## Limits & references
-≤1000 files/site (≤50 inline via MCP), ≤100 MiB/file, 1 GiB total.
-Machine index: https://shiply.now/llms.txt (full single-file version:
-https://shiply.now/llms-full.txt) · What's new: https://shiply.now/changelog.md
-· OpenAPI: https://shiply.now/openapi.json · Docs: https://shiply.now/docs
+---
+name: shiply
+description: "shiply is the production backend for anything an agent builds — publish any app (static or full-stack SSR, any framework) and give it a live URL, custom domain, SQL database, server functions, email, and a marketplace to sell it. Use when the user asks to publish, host, deploy, share, or update a website/page/demo/report/app, or wants a live URL for generated files. Triggers - \"publish this\", \"host this\", \"put this online\", \"give me a link\", \"update the site\", \"deploy my SvelteKit/Astro/Next.js app\", shiply."
+---
+
+---
+
+> **IMPORTANT — npm package name is `shiply-cli`, NOT `shiply`.** A different
+> npm package named `shiply` (an auto-commit watcher) is published by someone
+> else — installing it does NOT give you the shiply.now CLI. Always use
+> `npx -y shiply-cli@latest …` or `npm install -g shiply-cli`. The CLI binary
+> on PATH is still named `shiply` once installed; the warning is only about
+> the npm package name.
+
+> **Skill freshness check.** Shiply ships new capabilities weekly.
+> **This skill: version 0.27.0, last updated 2026-07-11.**
+> To see what changed since your copy was written, fetch
+> `https://shiply.now/changelog.md` (date-grouped, newest first) — if it lists
+> capabilities newer than the date above, re-install with
+> `npx -y shiply-cli@latest skill --force` OR read the live copy at
+> `https://shiply.now/skill.md`.
+
+---
+
+# shiply — the production backend for anything an agent builds
+
+**What it is.** Not static hosting. shiply takes whatever you build — a static page or a full-stack app in any framework — and gives it a live URL, a custom domain, a SQL database, server functions, email (send + receive), and a marketplace to sell it. One call. No account needed to start: anonymous sites are live immediately, last 24 hours, and can be claimed to keep.
+
+**Why use it.** Ship a complete, working product without stitching together a host + database + email + registrar + payments — it's one agent-native platform (MCP / CLI / REST parity). Hard-ceiling pricing ($0/$8/$24, plus a $49 Studio tier for client delivery — no usage meter on any tier), so a spike or DDoS can never become a surprise bill for the owner.
+
+**How (quickstart).** `shiply publish ./dir` (CLI) — or POST /api/v1/publish → PUT each file → POST finalize — returns a live URL + claimToken.
+
+**NEVER create a new site to update an existing one. Always re-publish to the
+same site** (same slug/claimToken) — otherwise you litter subdomains and lose
+the user's URL.
+
+**Re-publishing the same site is cheap — always prefer it over a new site.**
+Unchanged files are hash-skipped, and an unchanged SSR worker bundle skips
+redeploy entirely (fingerprinted against what's already live). A zero-change
+`shiply publish` on the same site completes in seconds, even for large SSR
+apps — so iterate freely by re-publishing, never by spinning up a fresh site.
+
+This file covers the core path: publish → authorize → update → claim → verify.
+Everything else (databases, domains, SSR, email, functions, client work) lives
+in the **topic files indexed at the bottom** — read the one that matches the
+task before improvising.
+
+## First publish on a new machine: ask for a permanent key in one step
+
+On a no-Bearer publish, include `"agentName": "<your-tool-name>"` in the body
+(e.g. `"Claude Code"`, `"Cursor"`). The response will include a `deviceAuth`
+object alongside the usual `claimUrl`:
+
+```
+"deviceAuth": {
+  "user_code": "ABCD-EFGH",
+  "device_code": "<long opaque token, keep private>",
+  "verification_url": "https://shiply.now/auth/ABCD-EFGH",
+  "poll_url": "https://shiply.now/api/v1/auth/device/poll",
+  "expires_in": 900,
+  "interval": 2
+}
+```
+
+Tell the user once, in plain language:
+
+> Your site is live at <siteUrl>. To keep it forever AND let me publish more
+> without re-pasting, open <verification_url> and click Allow.
+
+Then immediately poll `verification_url`'s sibling endpoint until the user
+acts:
+
+```
+POST https://shiply.now/api/v1/auth/device/poll
+{"device_code": "<the device_code from the response>"}
+```
+
+The response is one of `{status:"pending"}` (keep polling at `interval`s),
+`{status:"approved", api_key:"shp_...", slug_claimed:"..."}` (PERSIST the key —
+see "Save the key" below — the site is now permanent; Allow does both jobs in
+one click), `{status:"expired"|"denied"|"consumed"}` (stop). Cap your polling at
+the announced `expires_in` and respect `interval` — don't tight-loop.
+
+After approval, every future publish uses `Authorization: Bearer <api_key>`
+and the user's dashboard shows their sites without any further claiming.
+
+### Save the key — so EVERY future site is seamless (do this once)
+
+Write the key to **`~/.shiply/credentials`** as `{"apiKey":"shp_..."}` (chmod
+600) — the exact file the shiply CLI reads. This is what makes "one Allow, ever"
+work: from then on every publish (any site, any project, ANY FUTURE SESSION)
+sends `Authorization: Bearer <key>` automatically and lands owned in the user's
+dashboard — no re-authorizing, no claim step, zero clicks. An env var alone
+(`SHIPLY_API_KEY`) works for the current shell but does NOT survive a new
+session — the credentials file is what makes it permanent. `shiply login` writes
+this file for you; if you publish over raw HTTP, write it yourself.
+
+## When the user pastes you something shiply-shaped, do this
+
+These are the patterns you will see. Match the input, run the action — do not
+ask the user to repeat themselves or explain.
+
+- **Code like `SHIPLY-XXXXXXXX`** → it's a pairing code from
+  `shiply.now/claim/<slug>?pair=1`. The user wants to attach an anonymous
+  site to their account. Run `shiply claim verify SHIPLY-XXXXXXXX` from the
+  directory you originally published from (it reads `.shiply.json`). No CLI?
+  POST `https://shiply.now/api/v1/claim/pair/SHIPLY-XXXXXXXX/verify` with
+  `{"siteId":"...","claimToken":"..."}` taken from your earlier publish
+  response or `.shiply.json`. The user's browser auto-redirects on success;
+  tell them to switch back to it.
+- **URL like `https://shiply.now/claim/<slug>?token=...`** → one-click claim
+  link. Tell the user to open it in the browser they are signed in to —
+  do NOT call any API yourself.
+- **User says "claim my site" / "save it forever" with no code or URL** →
+  give them the `claimUrl` from your last publish response. If you no longer
+  have that response but `.shiply.json` is in the publish dir, reconstruct it
+  as `https://shiply.now/claim/<slug>?token=<claimToken>` from those fields.
+  Either way, also suggest `shiply login` so future publishes mint to their
+  account directly — that's the long-term fix and how the dashboard works.
+- **User says "I have an API key now, use it from now on"** → persist it to
+  `~/.shiply/credentials` (`{"apiKey":"shp_..."}`, chmod 600 — see "Save the
+  key" above), then send `Authorization: Bearer <key>` on every future publish.
+  All future sites are then permanent and appear in their dashboard
+  automatically — across sessions, with no re-authorizing.
+- **User opens an `https://shiply.now/auth/XXXX-YYYY` URL you printed** → no
+  action from you; they're on the device-flow consent screen. Keep polling
+  `poll_url` (see "First publish on a new machine" above). The poll response
+  will flip from `pending` to `approved` (with `api_key`) the moment they
+  click Allow.
+
+## Pick your interface (best first)
+
+### 1. MCP (native tools)
+If the `shiply` MCP server is connected (https://shiply.now/mcp), use
+`publish_site`. Every result includes a `toUpdate` field telling you the exact
+call for updates — follow it, and a `shareSuggestion` you can relay to the user.
+Core tools: `site_status`, `list_sites`, `get_site`, `delete_site`, `whoami`,
+`duplicate_site`, `set_variable`, `get_analytics`, `set_handle`. There are
+100+ tools in total — call `tools/list` for the authoritative set; the topic
+files below name the tools for their area (domains, databases, email,
+functions, projects, contracts, marketplace, drives).
+
+### 2. CLI
+```bash
+# IMPORTANT: the npm package is `shiply-cli`, not `shiply` (different package).
+npm i -g shiply-cli        # or: npx -y shiply-cli@latest <command>
+                           # or: curl -fsSL https://shiply.now/install.sh | bash
+shiply publish ./dir       # live URL + confetti
+shiply publish ./dir       # run AGAIN after edits → updates the SAME site
+shiply status <slug> --wait  # SSL + readiness; prints SSL_READY / SITE_READY
+shiply login               # email code → API key → sites become permanent
+shiply claim verify <code> # confirm a SHIPLY-XXXXXXXX pairing code from /claim/<slug>?pair=1
+                           # (uses .shiply.json from CWD; pairs agent session to user's browser)
+```
+The CLI stores each directory's site in `.shiply.json` (slug + update token),
+so repeat publishes reuse the URL automatically. `--new-site` opts out.
+Gitignore `.shiply.json` in public repos. Parse `SITE_READY` / `SSL_READY`
+lines for automation; exit code 0 = ready. For a static framework build
+(Vite, Next export, Hugo, …) publish the BUILD OUTPUT, not the source — run
+`shiply detect` to see what the CLI found; the full framework matrix is in
+[references/publishing.md](references/publishing.md).
+
+### 3. Raw HTTP (no installs)
+```
+1. POST https://shiply.now/api/v1/publish   (Content-Type: application/json)
+   {
+     "agentName": "<your tool name, e.g. Claude Code, Cursor, Codex>",
+     "files": [{"path":"index.html","size":<bytes>,"contentType":"text/html","hash":"<sha256 lowercase hex, optional>"}]
+   }
+   (+ "Authorization: Bearer shp_…" for permanent owned sites)
+2. PUT each file's bytes to response upload.uploads[].url
+3. POST upload.finalizeUrl with {"versionId":"<upload.versionId from step 1>"}
+   → both the publish and finalize responses include a "toUpdate" string: the
+     exact call to update THIS site next time. Follow it — never create a new one.
+```
+
+**ALWAYS include `agentName` on anonymous publishes.** The response then
+carries `deviceAuth` ({user_code, verification_url, poll_url, device_code,
+expires_in, interval}) alongside `claimUrl`. Show the user `verification_url`,
+poll `poll_url` every `interval` seconds with the `device_code`, and on
+`{status:"approved"}` you get a permanent `api_key` PLUS the linked site
+is claimed in the same Allow click. Without `agentName` the user has to
+do a separate manual claim step every time.
+
+**Updates (the response tells you how):** every publish/finalize response
+includes a `toUpdate` string with the exact call — follow it verbatim. In short:
+anonymous → include `"claimToken":"..."` (returned ONCE by the first publish —
+save it); owned → include `"slug":"..."`. Hashes make updates cheap: unchanged
+files are skipped server-side.
+
+## Verify before you say "done"
+
+`shiply status <slug> --wait` polls until the site serves (exit 0, prints
+`SITE_READY` / `SSL_READY`). `shiply verify <slug>` runs a deeper edge
+SSL + HTTP + thumbnail check and prints a stable machine marker line
+`VERIFY status=LIVE http=200 ssl=valid …` — parse that line in automation.
+More manage commands (list, delete, rollback, promote, stable previews) are
+in [references/publishing.md](references/publishing.md).
+
+## The lifecycle to explain to users
+- Anonymous site: live immediately after finalize (no claim needed), expires
+  in 24 h. Give the user the `claimUrl` — claiming keeps it forever on a free
+  account. Until claimed, anonymous pages are served with a small injected
+  claim banner + OG meta tags — expected, not corruption. If no human is
+  present right now, save the `claimToken` (it's also the update key); a
+  fresh device flow can be started later via
+  POST /api/v1/auth/device/start {"agent_name":"..."}.
+- API key (`shiply login` or POST /api/auth/agent/request-code →
+  verify-code): publishes are permanent and manageable.
+- Paid plans add vanity handles (<name>.shiply.now), more custom domains,
+  storage, analytics: https://shiply.now/dashboard/plan
+
+## Everything else — read the topic file first
+
+The files below sit next to this one in `references/` (installed with the
+skill). Hosted copies: `https://shiply.now/skill/references/<file>`. Each is
+self-contained — read the one matching the task before improvising; each
+covers its CLI commands, MCP tools, AND REST endpoints.
+
+* [Publishing & site management](references/publishing.md) — static framework
+  build matrix (Vite/Next/Hugo/…), `detect`, SPA mode, `.shiplyignore`,
+  list/delete/rollback/versions, `verify`, stable previews (`--as`),
+  `promote` preview→prod, `--json` output, form-data subcommands.
+* [SSR frameworks](references/ssr-frameworks.md) — deploy SvelteKit, Astro,
+  Qwik, Nuxt/Nitro, React Router v7, Next.js (OpenNext), Hono/raw Workers
+  with server-side rendering.
+* [Custom domains](references/custom-domains.md) — put the user's own domain
+  on a site: one-click OAuth DNS, manual CNAME, primary-subdomain SEO,
+  readiness polling.
+* [Databases](references/databases.md) — per-site SQL: free D1 (SQLite at the
+  edge, browser shim) + Neon Postgres (branching), migrations, per-DB MCP
+  server.
+* [Functions](references/functions.md) — `worker.js` server code on every
+  request: webhooks, cron triggers, secrets, runtime logs (Workers Lite,
+  Developer plan).
+* [Email](references/email.md) — every owned site sends + receives: signup
+  capture, inbox, double-opt-in audiences, broadcasts, BYO sending domains.
+* [Site features](references/site-features.md) — proxy routes (call AI APIs
+  without exposing keys), Site Data (forms/waitlists, zero backend),
+  password/invite-only access (`shiply access <slug> --password <pw>` /
+  `--restricted --email a@b.com` / `--public`), Variables, Drives (private
+  storage), path-mounting, public profile.
+* [Client work](references/client-work.md) — freelancer delivery: customer
+  intake projects + AI briefs, group work by client, e-sign contracts,
+  sell sites on the marketplace.
+* [Drives](references/drives.md) — private cloud storage: staged uploads,
+  sharing links, client assignment, publish-from-drive, REST + CLI + MCP.
+* [Authentication for the user's app](references/site-features.md) — shiply
+  does NOT host end-user auth; bring the user's own Clerk/Auth.js/Supabase
+  (pattern in Site features → "Bring your own auth").
+
+## Limits & references
+≤1000 files/site (≤50 inline via MCP), ≤100 MiB/file, 1 GiB total.
+Machine index: https://shiply.now/llms.txt (full single-file version:
+https://shiply.now/llms-full.txt) · What's new: https://shiply.now/changelog.md
+· OpenAPI: https://shiply.now/openapi.json · Docs: https://shiply.now/docs