shiply-cli 0.24.0 → 0.25.1

package/skill/references/client-work.md

@@ -0,0 +1,159 @@
+---
+type: reference
+title: Client work (projects, clients, contracts, marketplace)
+description: Freelancer delivery — customer intake projects with AI briefs, grouping work by client, e-sign contracts with amendments, and selling built sites on the marketplace via Stripe Connect.
+timestamp: 2026-07-04
+---
+
+# Client work — projects, clients, contracts, marketplace
+
+Part of the shiply skill (see SKILL.md for publish basics). All of it Bearer-
+key authenticated.
+
+## Projects — customer intake + AI brief
+
+When a dev needs to capture a real client brief, they spin up a **project**:
+the dashboard (or `shiply project create`) mints a one-URL intake form to
+share with the customer. The customer fills a 10-step wizard, attaches
+files, hits submit. An AI brief generator (MiniMax-M2 with Anthropic
+fallback) turns the answers into a structured brief the dev reviews and
+edits inline. All files flow into a per-project drive folder.
+
+MCP tools:
+```
+list_projects       — your projects (filter status/q)
+create_project      — start a new intake; pass customerName/customerEmail to email them the link
+get_project         — full project + brief
+update_brief        — patch brief jsonb (after AI generation)
+regenerate_brief    — re-run AI from current intake responses
+archive_project / restore_project — lifecycle
+list_project_files  — files uploaded by the customer
+resend_intake_invite — re-email the customer their intake link (requires customerEmail on project)
+```
+
+REST: `POST/GET /api/v1/projects · GET/PATCH /api/v1/projects/{id} ·
+POST /api/v1/projects/{id}/regenerate-brief`
+(archive: `PATCH /api/v1/projects/{id}` with `{"status":"archived"}` — no
+dedicated `/archive` route).
+
+CLI: `shiply project ls · shiply project create <label> [--customer-email <e>]
+[--customer-name <n>] · shiply project get <id> · shiply project archive <id>`
+
+Docs: https://shiply.now/docs/projects
+
+## Group work by client (optional, for freelancers)
+
+Building sites for clients? Pass an optional `client` (a name or email) on any
+`publish_site`, `create_drive`, or `create_project` call — shiply
+create-or-finds the client by email and files everything you ship for them
+(sites, drop-box, intake, contracts) under one customer view in the dashboard.
+A project's customer **is** the site's client (same email-keyed identity), so
+`create_project` already links automatically whenever you pass
+`customerEmail` — no extra step. There is no `create_client` tool and never a
+CRM step: the client record self-assembles from the calls you already make.
+`publish_site` echoes the `resolvedClientId` — reuse it across the session so
+drive/intake/contract all land under the same client. List calls take an
+optional `clientId` filter (`list_sites`/`list_drives`/`list_projects`).
+Omit `client` for personal projects; shiply works identically.
+CLI: `--client "<name-or-email>"` on publish/drive/project, plus
+`shiply client ls|show`.
+
+## Contracts — draft, sign, amend (extends Projects)
+
+Once a project reaches `brief_ready`, the dev drafts a signed contract from
+the brief, the customer e-signs in the portal (typed-name + checkbox), and
+the dev amends it later as scope evolves. A signed contract is immutable
+— any change is a new amendment row chained off the parent. The portal
+sends the customer; the dev can resend / remind / retract. A 7-day
+reminder cron nudges unsigned contracts automatically.
+
+MCP tools:
+```
+contract_draft   — draft a contract from a brief_ready project (returns the new contract id)
+contract_send    — flip status='sent', fire customer email (parent OR amendment)
+contract_amend   — create an amendment draft on a SIGNED parent (scopeDelta required, fee + date optional)
+contract_status  — read state + amendments (poll this to see status='signed')
+contract_pdf     — base64-encoded signed PDF (parent + cert + signed amendments)
+```
+
+Edit-before-send today is REST-only: `PATCH /api/v1/contracts/{id}` lets
+the dev tweak the 8 fields (scopeSummary, feeCents, currency, dates,
+revisionCount, revisionOverageCents, jurisdiction). After PATCH, call
+`contract_send` to fire it. Amendments are sent the same way (call
+`contract_send` with the amendment id returned by `contract_amend`).
+
+Example agent flow (draft → tweak fee → send → poll → amend):
+1. `contract_draft({projectId})` → returns `{id, scopeSummary, feeCents:null, ...}`
+2. `PATCH /api/v1/contracts/{id}` `{feeCents: 450000}` (Bearer key)
+3. `contract_send({contractId: id})` → project flips to `contract_sent`
+4. Poll `contract_status({contractId: id})` until `contract.status === 'signed'`
+5. `contract_amend({parentContractId: id, scopeDelta: "Add login flow", feeDeltaCents: 50000})` → returns the amendment row
+6. `contract_send({contractId: amendment.id})` (no PATCH needed if the amend fields are right)
+
+REST (Bearer for dev, portal cookie for customer):
+`POST /api/v1/projects/{id}/contracts` (draft) ·
+`GET/PATCH /api/v1/contracts/{id}` (read either-party / dev edit) ·
+`POST /api/v1/contracts/{id}/send` (dev) ·
+`POST /api/v1/contracts/{id}/view` (customer ping) ·
+`POST /api/v1/contracts/{id}/sign` (customer e-sign) ·
+`POST /api/v1/contracts/{id}/retract` (dev; `?recoverAsDraft=true` to
+recover the draft instead of voiding) ·
+`POST /api/v1/contracts/{id}/amend` (dev; signed parents only) ·
+`POST /api/v1/contracts/{id}/remind` ·
+`POST /api/v1/contracts/{id}/resend` (manual nudges, rate-limited 3/24h) ·
+`GET /api/v1/contracts/{id}/pdf` (binary, signed only).
+
+`contract_pdf` returns `{filename, contentType:"application/pdf", base64,
+byteLength}` so the MCP client can decode and save the bytes.
+
+CLI: `shiply contract list <project-id>`, `shiply contract draft
+<project-id>`, `shiply contract show <contract-id>`, `shiply contract send
+<contract-id>`, `shiply contract pdf <contract-id> -o file.pdf`, `shiply
+contract amend <id> --scope "…" [--fee-delta N] [--target-date YYYY-MM-DD]`,
+`shiply contract retract <id> [--keep-as-draft]`.
+
+Docs: https://shiply.now/docs/contracts
+
+## Marketplace — sell built sites
+
+Devs can list any owned site for sale: set a price + short pitch, choose
+standard or custom terms, pick a jurisdiction. Stripe Connect Express
+handles seller payouts — sellers complete a one-time onboarding before
+listing (`get_connect_status` returns the onboarding URL when needed).
+Buyers pay via Stripe Checkout; on `checkout.session.completed` the
+webhook flips the order to `paid` and transfers site ownership
+atomically. Refunds are available within the order's refund window
+(`refundExpiresAt`); a refund reverts ownership to the seller.
+
+Prices are passed as `priceCents` (whole-dollar cents between 100 and
+999900). `termsMode='standard'` uses shiply's template; `'custom'`
+requires `termsCustom` ≥50 chars.
+
+MCP tools:
+```
+list_listings    — my listings
+create_listing   — list a site (siteSlug, priceCents, pitch?, termsMode, jurisdiction, ...)
+update_listing   — change price/pitch/status (draft|live|paused)
+delete_listing   — pulls off marketplace (sets status=draft)
+list_my_sales    — orders where I'm the seller
+list_my_orders   — orders where I'm the buyer
+refund_order     — issue Stripe refund (within refund window; goes back to buyer)
+get_connect_status — Stripe Connect onboarding state + actionable URL
+```
+
+REST: `POST /api/v1/listings · PATCH /api/v1/listings/{id} ·
+POST /api/v1/listings/{id}/checkout · POST /api/v1/orders/{id}/refund ·
+GET /api/v1/connect/status`
+(no GET listing index over REST yet — use the MCP `list_listings` /
+`list_my_sales` / `list_my_orders` tools for machine output, or the
+dashboard `/dashboard/sales` page for humans.)
+
+CLI: `shiply listing ls · shiply listing create <site-slug> --price <cents>
+--jurisdiction "<region>" · shiply listing rm <slug> --id <listing-id>`
+
+**Stripe Connect note:** Sellers must complete one-time Stripe Connect
+onboarding before listing. Call `get_connect_status` first — when status
+isn't `'ready'` it returns an `onboardingUrl` you should hand to the
+user as a clickable link.
+
+Docs: https://shiply.now/docs/marketplace

package/skill/references/custom-domains.md

@@ -0,0 +1,87 @@
+---
+type: reference
+title: Custom domains
+description: Serve a site at the user's own domain — one-click OAuth DNS (Cloudflare, GoDaddy, IONOS), manual CNAME fallback, subdomain mapping, primary-hostname SEO, readiness polling.
+timestamp: 2026-07-04
+---
+
+# Custom domains
+
+Part of the shiply skill (see SKILL.md for publish basics). Serve a site at
+`www.yourdomain.com` instead of a `*.shiply.now` URL. Requires a paid plan and
+a Bearer API key.
+
+## The agent sequence (do it in this order)
+
+1. Confirm the user is authenticated and on a paid plan (`whoami` over MCP, or
+   `shiply status`).
+2. Add the root domain — this registers it and detects the DNS provider
+   (cloudflare, godaddy, ionos, or manual).
+3. **Supported provider detected** → start the one-click OAuth connect; it
+   returns a URL. SHOW THE USER that URL and ask them to open it in their
+   browser to authorize DNS writes. Wait for their confirmation.
+   **Provider is "manual"** → show the user the CNAME record returned by
+   step 2 (target: `cname.shiply.now`) and ask them to add it at their
+   registrar. Wait for confirmation.
+4. Map the subdomain to the site. The first subdomain you add for a site is
+   primary by default; later mappings start non-primary and 301-redirect to it.
+5. (Optional, SEO) Set the primary hostname between apex and www — sibling
+   hostnames 301-redirect to it, preserving path + query. Fixes duplicate
+   content.
+6. Poll the check endpoint until `ready: true` (usually 1–5 minutes), then
+   tell the user their domain is live.
+
+## CLI commands
+
+```bash
+shiply domain add example.com               # register a root domain (detects provider)
+shiply domain connect example.com           # one-click OAuth DNS setup (Cloudflare, GoDaddy, IONOS, etc.)
+shiply domain sub add www.example.com --site my-site   # map a subdomain → site
+shiply domain ls                            # list all domains + subdomains + status
+shiply domain sync example.com              # re-sync DNS records with a connected provider
+shiply domain primary <hostname>            # mark hostname canonical (siblings 301)
+```
+
+For one-click connect (`shiply domain connect`), the CLI prints an
+authorization URL — the user must open it in a browser and approve the OAuth
+grant before DNS is written.
+
+For unsupported providers, `shiply domain add` returns the CNAME record to add
+manually: `www CNAME cname.shiply.now`
+
+Check status after connecting:
+```bash
+shiply status www.example.com --wait   # polls until SSL_READY + SITE_READY; exit 0 when live
+```
+
+## MCP tools
+
+| Tool | Purpose |
+|------|---------|
+| `add_custom_domain` | Add a root domain and detect the provider |
+| `connect_provider` | Start OAuth → returns `{ url }` (show to user to authorize) |
+| `add_subdomain` | Map a subdomain to a site slug |
+| `set_primary_subdomain` | Pick the canonical URL; siblings 301-redirect (SEO fix) |
+| `check_custom_domain` | Live CNAME + SSL + readiness probe |
+| `sync_dns` | Re-push DNS records to a connected provider |
+| `list_custom_domains` | List all domains and their subdomain mappings |
+| `remove_custom_domain` | Remove a domain and all its mappings |
+
+## REST endpoints (`/api/v1/custom-domains`)
+
+```
+GET    /api/v1/custom-domains                          list domains
+POST   /api/v1/custom-domains                         add domain { domain }
+DELETE /api/v1/custom-domains/{domain}                remove domain
+POST   /api/v1/custom-domains/{domain}/subdomains     add subdomain { subdomain, slug }
+POST   /api/v1/custom-domains/{domain}/subdomains/{id}/primary   mark hostname canonical (siblings 301)
+POST   /api/v1/custom-domains/{domain}/connect        start OAuth → { url }
+POST   /api/v1/custom-domains/{domain}/sync-dns       re-sync DNS
+POST   /api/v1/custom-domains/{domain}/check          live status → {cname, ssl:{valid,issuer,daysLeft}, http, ready}
+```
+
+All require `Authorization: Bearer shp_…`. Poll the check endpoint until
+`ready:true` before telling the user it's done.
+
+Vanity handle (paid, no domain needed): `POST /api/v1/publish/<slug>/handle
+{"handle"}` → `<handle>.shiply.now`. MCP: `set_handle`.

package/skill/references/databases.md

@@ -0,0 +1,108 @@
+---
+type: reference
+title: Databases (D1 + Neon Postgres)
+description: Per-site SQL — free Cloudflare D1 (SQLite at the edge, browser query shim) and Neon Postgres (developer plan, copy-on-write branching), migrations, attach, per-DB MCP server.
+timestamp: 2026-07-04
+---
+
+# SQL databases (Cloudflare D1 + Neon Postgres)
+
+Part of the shiply skill (see SKILL.md for publish basics). Two engines, same
+CLI/REST/MCP surface. **D1 (SQLite at the edge)** is free on every plan and
+queryable from the browser via a built-in fetch shim — no API key in the page.
+**Neon Postgres** is a developer-plan add-on with copy-on-write branching; the
+connection URI is encrypted at rest and surfaced to the site's Worker as
+`env.DATABASE_URL`.
+
+## D1 (default)
+
+```bash
+shiply db create app                      # provision a D1 (binding SITE_DB)
+shiply db ls                              # list (name, provider, size, attached site)
+shiply db sql app "SELECT 1"              # one-shot query against your account
+shiply db sql app "SELECT * FROM t WHERE id=?1" --params '[42]'
+shiply db migrate app ./migrations        # apply every *.sql in dir, sorted
+shiply db attach app --site my-site       # bind an existing DB to another site
+shiply db delete app --yes                # drop the DB and every row
+```
+
+Run `shiply db create` inside a publish directory: it records the new
+`databaseId` into `.shiply.json` so the next `shiply publish` auto-attaches
+it. Site code then calls the shim:
+
+```js
+fetch('/_shiply/db/SITE_DB/query', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ sql: 'SELECT * FROM posts', params: [] }),
+}).then(r => r.json())  // → { results: [...], meta: {rows_read, rows_written, duration} }
+```
+
+**Public by default**: the shim has no visitor auth, so anyone who can fetch
+the site can run any SQL. Until a private-mode gate ships, recommend it
+strictly as a SELECT-only public data layer. Reads always work; writes hit
+402 once the DB exceeds the plan storage cap (Founder Special 100 MB,
+Hobby 1 GB, Developer 10 GB).
+
+D1 caveats: SQLite dialect, no cross-DB joins, 10 GB per-DB ceiling.
+
+## Neon Postgres (developer plan)
+
+Pass `--postgres` on create. One isolated Neon project per database;
+binding defaults to `DATABASE_URL`. Free / Hobby get `402
+payment_required` — point the user at https://shiply.now/dashboard/plan.
+
+```bash
+shiply db create app --postgres           # provision Neon (~5–10s)
+shiply db branch app dev                  # copy-on-write branch off main
+shiply db branches app                    # list branches
+shiply db delete-branch dev --yes         # drop branch + endpoint
+shiply db merge dev                       # NO-OP — prints pg_dump tip (see below)
+```
+
+After the next `shiply publish` the serving Worker receives
+`env.DATABASE_URL`. Minimal example:
+
+```js
+import { neon } from '@neondatabase/serverless'
+const sql = neon(process.env.DATABASE_URL)
+const rows = await sql`SELECT now()`
+```
+
+Anything that speaks Postgres works: `pg`, `postgres`, drizzle, kysely,
+prisma (with the Neon adapter). Connection URIs are AES-256-GCM encrypted
+at rest.
+
+**Branching is the headline feature.** Branches are cheap, instant,
+copy-on-write forks of `main`. Bind a publish to a specific branch with
+`shiply publish --preview-branch=<branchDbId>` (use the `site_databases`
+row id printed by `shiply db branch`, NOT the raw Neon branch id) —
+great for preview deploys and safe schema rollouts.
+
+**`shiply db merge` is intentionally a no-op.** Neon has no server-side
+merge. To promote branch data into the parent:
+`pg_dump "$BRANCH_DATABASE_URL" | psql "$PARENT_DATABASE_URL"`.
+Run schema migrations against both branches to keep them aligned.
+
+**Not yet supported on Neon**: branch-of-branch (branches off `main`
+only), auto preview-branch on every publish, cross-region projects.
+
+## REST + MCP (provider-agnostic)
+
+REST (Bearer `shp_…`): `POST /api/v1/databases` (pass `"provider":"neon"`
+for Postgres) to create, `POST /api/v1/databases/{id}/query` to query (works
+for D1 and Neon), `POST .../attach` to bind, `DELETE` to drop. Neon-only:
+`POST/GET/DELETE /api/v1/databases/{id}/branches[/{branchId}]` (400 on
+D1 rows).
+
+Per-DB MCP server (so an agent can be scoped to one DB):
+`https://shiply.now/api/mcp/db/<id>/sse` (or `/mcp` for streamable-http),
+Bearer `shp_…` — tools: `db_query`, `db_list_tables`, `db_schema`. The same
+three tools work against both providers; `db_schema` introspects
+`sqlite_master` (D1) or `information_schema` (Neon).
+
+Plan quotas: every account gets 1 free D1 (Founder Special: 100 MB; Hobby:
+5 × 1 GB; Developer: unlimited × 10 GB). Size sampled every 15 min; writes
+blocked at 402 over plan cap; reads still work.
+
+Full docs: https://shiply.now/docs/databases

package/skill/references/email.md

@@ -0,0 +1,147 @@
+---
+type: reference
+title: Email (capture, send, inbox, broadcast, sending domains)
+description: Every owned site has a real email address — public signup capture with double opt-in, authenticated send, inbox reading, audience broadcasts, and BYO verified sending domains.
+timestamp: 2026-07-04
+---
+
+# Agent Email — inbox, send, capture, broadcast (built into every owned site)
+
+Part of the shiply skill (see SKILL.md for publish basics). Every owned site
+has a real email address and can send, receive, capture signups, and broadcast
+— in one line. Like AgentMail, built into the site.
+
+## Capture (public form, zero-config — but the SITE must be owned)
+
+```
+POST /.shiply/email  { "email": "user@example.com", ...anyExtraFields }
+```
+
+No manifest needed. Works on the **relative path** from the published page.
+On success: record lands in the site inbox + owner gets a notification ping +
+a double-opt-in confirmation email goes to the visitor (all on by default).
+**Owned sites only** — anonymous sites get `403 email_requires_account` (claim
+the site first). A non-empty `company` field is treated as a honeypot (bot
+submissions are silently dropped). Caps: 16 KB body, 30 fields max.
+
+## Send (authenticated — Bearer key only)
+
+The public page can NEVER send; only authenticated calls can.
+
+```
+POST https://shiply.now/api/v1/email/send
+Authorization: Bearer shp_…
+{ "slug": "my-site", "to": "user@example.com", "subject": "Hi", "html": "<p>Hi</p>", "text": "Hi" }
+→ { "messageId": "..." }
+```
+
+## Read inbox
+
+```
+GET https://shiply.now/api/v1/email/inbox          # all sites
+GET https://shiply.now/api/v1/email/inbox?slug=my-site
+Authorization: Bearer shp_…
+```
+
+## Typed upgrade (optional)
+
+Declare an `email` block on a `.shiply/data.json` collection for typed fields +
+fine-grained control (see [site-features.md](site-features.md) for Site Data):
+
+```json
+{
+  "collections": {
+    "signups": {
+      "fields": { "email": { "type": "email", "required": true } },
+      "email": {
+        "emailField": "email",
+        "confirm": true,
+        "notify": true,
+        "audience": true
+      }
+    }
+  }
+}
+```
+
+All three flags default to `true`. With this manifest, POST to
+`/.shiply/data/signups` as usual — the `email` block activates the email
+layer on that collection.
+
+## Confirm / unsubscribe (public — in the confirmation email)
+
+```
+GET /api/email/<slug>/<collection>/confirm?token=<token>
+GET /api/email/<slug>/<collection>/unsubscribe?email=<address>
+```
+
+## Audience + broadcast
+
+Confirmed (double-opt-in) signups form a list. Broadcast to them:
+
+```
+POST /api/v1/publishes/<slug>/mailboxes/<collection>/broadcast
+Authorization: Bearer shp_…
+{ "subject": "Launch day", "html": "<p>We're live!</p>" }
+```
+
+Spam-checked before send; unsubscribe footer is auto-added; requires ≥1
+confirmed subscriber.
+
+Configure a mailbox: `GET/PATCH /api/v1/publishes/<slug>/mailboxes/<collection>`
+List contacts: `GET /api/v1/publishes/<slug>/mailboxes/<collection>/contacts?status=confirmed`
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `send_email` | Send transactional email from a site (Bearer) |
+| `list_site_inbox` | Read the inbox (all threads or filter by slug) |
+| `set_mailbox` | Configure a collection's mailbox settings |
+| `list_mailbox_contacts` | List audience contacts (filter by status) |
+| `send_mailbox_broadcast` | Broadcast to confirmed audience (spam-checked) |
+
+## CLI
+
+```bash
+shiply email send --site <slug> --to <address> --subject <subject> --html <html>
+shiply email inbox [--site <slug>]
+shiply mailbox set <slug> <collection> [--confirm] [--notify] [--from <domain>]
+shiply mailbox broadcast <slug> <collection> --subject <subject> --html <html>
+```
+
+Docs: https://shiply.now/docs/agent-email
+
+## Email demand tests (agent-managed — no Resend account needed)
+
+Validate an idea end-to-end: `create_test({ idea, headline, sub?, cta?,
+price? })` (MCP) deploys a capture landing page + provisions a confirmed-
+subscriber segment; returns `testId` + live `siteUrl`. Share the siteUrl.
+Visitors submit the form → shiply sends double-opt-in confirmation
+automatically → they click to confirm. `get_test_status({ testId })` → ONE
+merged object: funnel (views/signups/confirmed/conversionRate), email
+(delivered/opened/clicked/bounced), verdict (signal:
+strong|weak|inconclusive, confirmedSignupRate). CONFIRMED is the real demand
+signal (double opt-in). `send_broadcast({ testId, subject, html })` emails
+the confirmed audience (unsubscribe link auto-added). `list_tests()` — all
+tests for this key. `resend_confirmation({ testId, email })` — re-send the
+opt-in to one address.
+
+## Sending domains — outbound email on your domain
+
+For agents that want shiply to send emails (demand-test broadcasts, project
+intake invites, transactional notifications) from a custom verified domain
+instead of the shared shiply pool. Backed by Resend — add the DNS records
+they return at your registrar, then verify to re-check.
+
+MCP tools: `list_sending_domains`, `add_sending_domain` (returns DNS records
+to add), `verify_sending_domain`, `remove_sending_domain`.
+
+REST: `GET/POST /api/v1/sending-domains ·
+POST /api/v1/sending-domains/{id}/verify · DELETE /api/v1/sending-domains/{id}`
+
+CLI: `shiply sending-domain ls · shiply sending-domain add <domain> ·
+shiply sending-domain verify <id> · shiply sending-domain rm <id> --yes`
+
+Cannot be a `shiply.now` subdomain. Verified status flips once SPF +
+DKIM (+ MX for inbound) all check out.

package/skill/references/functions.md

@@ -0,0 +1,100 @@
+---
+type: reference
+title: Functions (Workers Lite)
+description: Server-side worker.js/worker.ts on every request — webhooks with signature verification, cron triggers, encrypted secrets, runtime logs. Developer plan.
+timestamp: 2026-07-04
+---
+
+# Functions (Workers Lite) — webhooks, cron, secrets, full backend
+
+Part of the shiply skill (see SKILL.md for publish basics). Plan-gated to
+Developer: Founder/Hobby see `402 payment_required`
+(upgrade: shiply.now/dashboard/plan).
+
+shiply Workers Lite lets a published site include server-side code that runs
+on every request. Use when the user needs:
+- A webhook receiver (Stripe, GitHub, etc.) with raw body + signature verification
+- A cron job (daily reminders, periodic sync, retention emails)
+- A privileged API call using secrets (Stripe key, OpenAI key) without exposing them to the browser
+- An authenticated mutation on D1 / Neon (do the auth check in the function before writing)
+
+## How it works
+
+Author `worker.js` (or `worker.ts`) at the publish root. On `shiply publish`,
+shiply compiles (TS) + deploys it as a per-site Cloudflare Worker bound to
+the site's hostname. The worker handles every request; pass static asset
+requests through `env.ASSETS.fetch(request)`.
+
+```ts
+import { verifyStripeSig, json } from 'shiply-runtime'
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const url = new URL(req.url)
+    if (url.pathname === '/api/webhooks/stripe' && req.method === 'POST') {
+      const body = await req.text()
+      if (!await verifyStripeSig(body, req.headers.get('stripe-signature'), env.STRIPE_WEBHOOK_SECRET)) {
+        return new Response('bad sig', { status: 400 })
+      }
+      // ... handle event, write to env.SITE_DB
+      return new Response('ok')
+    }
+    return env.ASSETS.fetch(req)
+  },
+  async scheduled(event: ScheduledEvent, env: Env) {
+    if (event.cron === '0 9 * * *') { /* daily job */ }
+  }
+}
+```
+
+`.shiply/crons.json` declares cron schedules. `.shiply/secrets.json` declares
+secret names (values set via CLI/MCP, never reach the publish payload).
+
+Runtime: V8 isolate — no Node APIs, no Buffer; use Web Crypto + Web Fetch.
+Companion npm package `shiply-runtime` exports `verifyStripeSig`, `readJson`,
+`json`, `errorResponse`.
+
+## Bindings available in `env`
+
+- `env.ASSETS` — fall through to static (`env.ASSETS.fetch(request)`)
+- `env.SITE_DB` — attached D1 (if `shiply db attach` was run)
+- `env.<NAME>` — each shiply Variable becomes a plain-text env var
+- `env.<NAME>` — each secret set via `set_secret` is encrypted, accessible as env var
+
+## MCP tools
+
+| Tool | Purpose |
+|---|---|
+| `deploy_function` | Deploy a Worker function (alternative to publish auto-detection) |
+| `get_function` | Read the deployed source + metadata |
+| `remove_function` | Strip function + secrets + crons; fall back to static |
+| `set_secret` / `list_secrets` / `remove_secret` | Manage CF Worker secrets |
+| `set_cron` / `list_crons` / `remove_cron` | Manage cron triggers |
+| `get_function_logs` | Read recent runtime logs (CF Observability, 7-day, newest-first) + a dashboard deep-link |
+
+## CLI
+
+```bash
+shiply publish .                            # auto-detects worker.js + crons.json + secrets.json
+shiply function deploy <slug>               # alternative: upload worker.js without re-publishing
+shiply function deploy <slug> --ts          # uploads worker.ts (server-side compile)
+shiply secret set <slug> STRIPE_KEY sk_xxx  # set secret value
+shiply cron set <slug> /api/daily "0 9 * * *"
+shiply logs <slug>                          # recent worker logs (newest-first); --limit N --since MIN --json
+```
+
+## REST
+
+`POST/GET/DELETE /api/v1/sites/{slug}/function` (body: {source, lang?, crons?})
+· `POST/GET /api/v1/sites/{slug}/secrets` {"name","value"}
+· `DELETE /api/v1/sites/{slug}/secrets/{name}`
+· `GET/POST/DELETE /api/v1/sites/{slug}/crons` {"path","schedule"}
+· `GET /api/v1/sites/{slug}/logs?limit&since` (recent runtime logs, newest-first)
+
+## Limits + plan
+
+- 1 MB compiled script size, 30s CPU per request, V8 isolate runtime (no Node APIs)
+- 50 secrets, 20 cron triggers per site
+- Plan-gated to Developer
+
+Docs: https://shiply.now/docs/functions