shiply-cli 0.7.0 → 0.12.0

package/dist/login.js

@@ -0,0 +1,60 @@
+import { hostname } from 'node:os';
+import { api, ApiError } from './publish.js';
+/** RFC 8628 client. The default for `shiply login`: no email round-trip,
+ *  no manual code paste — just open a URL, click Allow, return to the
+ *  terminal. The user can override the displayed agent name with --name
+ *  (otherwise we synthesize from hostname). */
+export async function loginViaDeviceFlow(base, agentNameOverride) {
+    const agentName = (agentNameOverride ?? `shiply-cli on ${hostname()}`).trim().slice(0, 80);
+    const start = await api(`${base}/api/v1/auth/device/start`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ agent_name: agentName }),
+    });
+    // Print the URL prominently — the user must open it. We don't auto-launch
+    // a browser because the CLI runs in headless contexts (CI, SSH, containers)
+    // where opening a local browser would either fail silently or open in the
+    // wrong machine. Showing the URL is the predictable thing.
+    console.log('');
+    console.log(`  → Open this URL to authorize ${agentName}:`);
+    console.log('');
+    console.log(`     ${start.verification_url}`);
+    console.log('');
+    console.log(`  Code shown there: ${start.user_code}`);
+    console.log(`  Waiting up to ${Math.round(start.expires_in / 60)} minutes…`);
+    const deadline = Date.now() + start.expires_in * 1000;
+    const intervalMs = Math.max(start.interval, 1) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        let poll;
+        try {
+            poll = await api(`${base}/api/v1/auth/device/poll`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ device_code: start.device_code }),
+            });
+        }
+        catch (e) {
+            // Transient network blip — don't kill the whole flow, the user has time.
+            if (e instanceof ApiError && e.status >= 500)
+                continue;
+            throw e;
+        }
+        if (poll.status === 'approved' && poll.api_key) {
+            return { ok: true, apiKey: poll.api_key, slug: poll.slug_claimed ?? null };
+        }
+        if (poll.status === 'denied')
+            return { ok: false, reason: 'denied by you in the browser' };
+        if (poll.status === 'expired')
+            return { ok: false, reason: 'authorization request expired' };
+        if (poll.status === 'consumed') {
+            // Another process already collected the key for this device_code; we
+            // can't recover it. Tell the user to retry.
+            return { ok: false, reason: 'this authorization was already collected elsewhere — retry to mint a fresh one' };
+        }
+    }
+    return { ok: false, reason: 'authorization timed out — re-run `shiply login` to try again' };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/publish.js

@@ -40,6 +40,8 @@ export async function publish(dir, opts = {}) {
             ...(opts.spaMode ? { spaMode: true } : {}),
             ...(opts.claimToken ? { claimToken: opts.claimToken } : {}),
             ...(opts.slug ? { slug: opts.slug } : {}),
+            ...(opts.attachDatabaseId ? { attachDatabaseId: opts.attachDatabaseId } : {}),
+            ...(opts.previewBranchDbId ? { previewBranchDbId: opts.previewBranchDbId } : {}),
         }),
     });
     await uploadAll(dir, created.upload.uploads);

package/package.json

@@ -1,23 +1,38 @@
-{
-  "name": "shiply-cli",
-  "version": "0.7.0",
-  "description": "Publish static sites to shiply.now from the command line — instant web hosting for agents.",
-  "license": "MIT",
-  "type": "module",
-  "bin": { "shiply": "dist/index.js" },
-  "files": ["dist", "skill", "README.md"],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "engines": { "node": ">=18" },
-  "keywords": ["shiply", "hosting", "static", "deploy", "agents", "publish"],
-  "homepage": "https://shiply.now",
-  "devDependencies": {
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
-    "@types/node": "^22.15.0"
-  }
-}
+{
+  "name": "shiply-cli",
+  "version": "0.12.0",
+  "description": "Publish static sites to shiply.now from the command line — instant web hosting for agents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "shiply": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "shiply",
+    "hosting",
+    "static",
+    "deploy",
+    "agents",
+    "publish"
+  ],
+  "homepage": "https://shiply.now",
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "@types/node": "^22.15.0"
+  }
+}

package/skill/SKILL.md

@@ -1,115 +1,359 @@
----
-name: shiply
-description: Publish static sites to the web instantly with shiply.now and manage them (updates, SSL checks, custom domains, variables). Use when the user asks to publish, host, deploy, share, or update a website/page/demo/report, or wants a live URL for generated files. Triggers - "publish this", "host this", "put this online", "give me a link", "update the site", shiply.
----
-
-# shiply — instant web hosting for agents
-
-shiply.now puts files on the web in seconds. No account needed to start:
-anonymous sites are live immediately, last 24 hours, and can be claimed into
-an account to keep them. The cardinal rule:
-
-**NEVER create a new site to update an existing one. Always re-publish to the
-same site** — otherwise you litter subdomains and lose the user's URL.
-
-## 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. Other tools: `site_status`, `list_sites`,
-`set_handle`, `set_variable`, `add_domain`, `check_domain`, `get_analytics`,
-`delete_site`, `rollback` via dashboard.
-
-### 2. CLI
-```bash
-npm i -g shiply-cli        # 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
-```
-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.
-
-### 3. Raw HTTP (no installs)
-```
-1. POST https://shiply.now/api/v1/publish
-   {"files":[{"path":"index.html","size":<bytes>,"contentType":"text/html","hash":"<sha256, 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":"..."}
-```
-**Updates:** anonymous → include `"claimToken":"..."` (returned ONCE by the
-first publish — save it); owned → include `"slug":"..."`. Hashes make updates
-cheap: unchanged files are skipped server-side.
-
-## The lifecycle to explain to users
-- Anonymous site: live instantly, expires in 24 h. Give the user the
-  `claimUrl` — claiming keeps it forever on a free account.
-- 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
-
-## Power features (Bearer key)
-- **Custom domains**: POST /api/v1/domains {"hostname","slug"} → tell the
-  user to CNAME the hostname to `cname.shiply.now` → cert auto-issues; poll
-  GET /api/v1/domains/{id}/check until `ready:true`.
-- **SSL/readiness checker**: `shiply status <slug-or-domain> --wait` or the
-  check endpoint — confirms certificate + serving before telling the user
-  it's done.
-- **Variables**: encrypted per-user KV for API keys the user's sites need
-  (GET/PUT /api/v1/variables, DELETE /api/v1/variables/{NAME}); Supabase can
-  be connected from the dashboard and lands here as SUPABASE_URL +
-  SUPABASE_ANON_KEY.
-- **Rollback**: POST /api/v1/publish/{slug}/rollback {"versionId"} flips any
-  finalized version live instantly.
-- **SPA**: pass `"spaMode":true` so deep links serve index.html.
-
-## Proxy routes — AI/API calls WITHOUT exposing keys
-NEVER embed API keys in published HTML/JS. Instead: store the key as a
-Variable (PUT /api/v1/variables), then include `.shiply/proxy.json` in the
-published files declaring routes, e.g. {"proxies":{"/api/chat":{"upstream":
-"https://openrouter.ai/api/v1/chat/completions","method":"POST","headers":
-{"Authorization":"Bearer ${OPENROUTER_API_KEY}"}}}}. The page then calls the
-relative path (fetch('/api/chat')) and shiply injects the secret server-side.
-Prefix routes "/api/db/*" forward subpaths (great for Supabase REST).
-Owned sites only; https public upstreams only. Docs: /docs/proxy-routes
-
-## Site Data — forms/waitlists/guestbooks with ZERO backend
-When the user wants to collect anything from visitors (waitlist, contact
-form, RSVP, guestbook): include `.shiply/data.json` in the published files,
-e.g. {"collections":{"signups":{"fields":{"email":{"type":"email",
-"required":true}},"access":{"read":"owner","insert":"public"}}}}, then have
-the page POST JSON to the relative path /.shiply/data/signups. Records are
-validated server-side; the owner reads them in the dashboard (Data section,
-CSV export) or GET /api/v1/publishes/<slug>/data/<collection> with a Bearer
-key. Owned sites only. Docs: /docs/site-data
-
-## Make a site private (paid plans)
-To password-protect or restrict a site: PATCH /api/v1/publishes/<slug>/access
-with {"mode":"password","password":"..."} or {"mode":"restricted",
-"allowedEmails":[...],"allowedDomains":[...]}, or set mode "public" to open it.
-MCP tool set_site_access does the same. Enforced before any content is served;
-changing settings signs current visitors out. Docs: /docs/access-control
-
-## Full React / Vue / Svelte / Astro apps — YES, they work
-shiply hosts complete framework apps. Publish the BUILD OUTPUT, never the
-source: run the build, then publish the output dir with SPA mode for
-client-routed apps. The CLI auto-detects source dirs and tells you the
-right command.
-- Vite/React/Vue/Svelte: `npm run build` then `shiply publish dist --spa`
-- Create React App: `npm run build` then `shiply publish build --spa`
-- Next.js: set `output: "export"` in next.config, `npm run build`, then
-  `shiply publish out` (no --spa; export emits real HTML per route)
-- Astro/static generators: `shiply publish dist`
-Use the CLI (not inline MCP files) for builds — hashed bundles often exceed
-the 50-file inline cap, and the CLI hash-skips unchanged chunks on updates.
-
-## Limits & references
-≤1000 files/site (≤50 inline via MCP), ≤100 MiB/file, 1 GiB total.
-Machine guide: https://shiply.now/llms.txt · OpenAPI:
-https://shiply.now/openapi.json · Docs: https://shiply.now/docs
+---
+name: shiply
+description: Publish static sites to the web instantly with shiply.now and manage them (updates, SSL checks, custom domains, variables). Use when the user asks to publish, host, deploy, share, or update a website/page/demo/report, or wants a live URL for generated files. Triggers - "publish this", "host this", "put this online", "give me a link", "update the site", shiply.
+---
+
+# shiply — instant web hosting for agents
+
+shiply.now puts files on the web in seconds. No account needed to start:
+anonymous sites are live immediately, last 24 hours, and can be claimed into
+an account to keep them. The cardinal rule:
+
+**NEVER create a new site to update an existing one. Always re-publish to the
+same site** — otherwise you litter subdomains and lose the user's URL.
+
+## 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:"..."}` (save the key as
+`SHIPLY_API_KEY`, 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.
+
+## 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"** → save it as
+  `SHIPLY_API_KEY` in your environment / config and send
+  `Authorization: Bearer <key>` on every future publish. All future sites
+  are then permanent and appear in their dashboard automatically.
+- **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.
+Other tools: `site_status`, `list_sites`, `get_site`, `set_handle`,
+`duplicate_site`, `set_variable`, `get_analytics`, `delete_site`, `whoami`,
+`add_custom_domain`, `connect_provider`, `add_subdomain`, `check_custom_domain`,
+`sync_dns`, `list_custom_domains`, `remove_custom_domain`
+(auto-DNS via OAuth provider connections — see **Custom domains** section below).
+
+Newer capabilities (use when relevant):
+- `set_site_access` — password / invite-only protect a site (paid).
+- `set_link` — mount another owned **public** site at a path on a host
+  (host/docs → target).
+- `set_profile` / `feature_site` — stand up the user's public portfolio at
+  <handle>.shiply.now and feature a public site on shiply.now/explore.
+- **Drives** (private cloud storage for files/notes/context): `list_drives`,
+  `create_drive`, `drive_put_file` (driveId "default", utf8/base64, ≤2 MB),
+  `drive_list_files`, `drive_delete_file`, `publish_from_drive` (snapshot a
+  drive into a live site). Great for agent memory and assets you don't want on
+  a public site.
+- `export_account` — JSON bundle of the user's data (no secrets).
+
+### 2. CLI
+```bash
+npm i -g shiply-cli        # 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.
+
+### 3. Raw HTTP (no installs)
+```
+1. POST https://shiply.now/api/v1/publish
+   {"files":[{"path":"index.html","size":<bytes>,"contentType":"text/html","hash":"<sha256, 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":"..."}
+```
+**Updates:** anonymous → include `"claimToken":"..."` (returned ONCE by the
+first publish — save it); owned → include `"slug":"..."`. Hashes make updates
+cheap: unchanged files are skipped server-side.
+
+## The lifecycle to explain to users
+- Anonymous site: live instantly, expires in 24 h. Give the user the
+  `claimUrl` — claiming keeps it forever on a free account.
+- 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
+
+## Custom domains
+
+Serve a site at `www.yourdomain.com` instead of a `*.shiply.now` URL. Requires a paid plan and a Bearer API key.
+
+### 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
+```
+
+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 (same operations via agent 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 |
+| `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}/connect        start OAuth → { url }
+POST   /api/v1/custom-domains/{domain}/sync-dns       re-sync DNS
+POST   /api/v1/custom-domains/{domain}/check          live status
+```
+
+All require `Authorization: Bearer shp_…`.
+
+## Power features (Bearer key)
+- **Custom domains**: see the **Custom domains** section above.
+  REST: `POST /api/v1/custom-domains {"domain"}` → add domain + detect provider.
+  Then `POST /api/v1/custom-domains/{domain}/connect` → OAuth one-click (show URL to user)
+  or add the CNAME manually. Map subdomains: `POST /api/v1/custom-domains/{domain}/subdomains {"subdomain","slug"}`.
+  Poll `POST /api/v1/custom-domains/{domain}/check` until `ready:true`.
+- **SSL/readiness checker**: `shiply status <slug-or-domain> --wait` or the
+  check endpoint — confirms certificate + serving before telling the user
+  it's done.
+- **Variables**: encrypted per-user KV for API keys the user's sites need
+  (GET/PUT /api/v1/variables, DELETE /api/v1/variables/{NAME}); Supabase can
+  be connected from the dashboard and lands here as SUPABASE_URL +
+  SUPABASE_ANON_KEY.
+- **Rollback**: POST /api/v1/publish/{slug}/rollback {"versionId"} flips any
+  finalized version live instantly.
+- **SPA**: pass `"spaMode":true` so deep links serve index.html.
+
+## Proxy routes — AI/API calls WITHOUT exposing keys
+NEVER embed API keys in published HTML/JS. Instead: store the key as a
+Variable (PUT /api/v1/variables), then include `.shiply/proxy.json` in the
+published files declaring routes, e.g. {"proxies":{"/api/chat":{"upstream":
+"https://openrouter.ai/api/v1/chat/completions","method":"POST","headers":
+{"Authorization":"Bearer ${OPENROUTER_API_KEY}"}}}}. The page then calls the
+relative path (fetch('/api/chat')) and shiply injects the secret server-side.
+Prefix routes "/api/db/*" forward subpaths (great for Supabase REST).
+Owned sites only; https public upstreams only. Docs: /docs/proxy-routes
+
+## Site Data — forms/waitlists/guestbooks with ZERO backend
+When the user wants to collect anything from visitors (waitlist, contact
+form, RSVP, guestbook): include `.shiply/data.json` in the published files,
+e.g. {"collections":{"signups":{"fields":{"email":{"type":"email",
+"required":true}},"access":{"read":"owner","insert":"public"}}}}, then have
+the page POST JSON to the relative path /.shiply/data/signups. Records are
+validated server-side; the owner reads them in the dashboard (Data section,
+CSV export) or GET /api/v1/publishes/<slug>/data/<collection> with a Bearer
+key. Owned sites only. Docs: /docs/site-data
+
+## SQL databases (Cloudflare D1 + Neon Postgres)
+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 APP_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/APP_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).
+
+### 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).
+
+**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` — 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). Full docs:
+https://shiply.now/docs/databases
+
+## Make a site private (paid plans)
+To password-protect or restrict a site: PATCH /api/v1/publishes/<slug>/access
+with {"mode":"password","password":"..."} or {"mode":"restricted",
+"allowedEmails":[...],"allowedDomains":[...]}, or set mode "public" to open it.
+MCP tool set_site_access does the same. Enforced before any content is served;
+changing settings signs current visitors out. Docs: /docs/access-control
+
+## Any static site works — frameworks + SSGs auto-detected
+shiply hosts any static site. Publish the BUILD OUTPUT, never the source:
+run the build, then publish the output dir with SPA mode for client-routed
+apps. The CLI auto-detects 16+ frameworks and tells you the right command.
+Run `shiply detect` to preview what it found without uploading.
+- Vite (React/Vue/Svelte/Solid/Qwik): `npm run build` then `shiply publish dist --spa`
+- Create React App: `npm run build` then `shiply publish build --spa`
+- Next.js: set `output: "export"` in next.config, `npm run build`, then
+  `shiply publish out` (no --spa; export emits real HTML per route)
+- Astro: `npm run build` then `shiply publish dist`
+- SvelteKit (adapter-static): `npm run build` then `shiply publish build --spa`
+- Nuxt: `npx nuxt generate` then `shiply publish .output/public`
+- Remix (client build): `npm run build` then `shiply publish build/client --spa`
+- Docusaurus: `npm run build` then `shiply publish build`
+- Hugo: `hugo` then `shiply publish public`
+- Jekyll: `bundle exec jekyll build` then `shiply publish _site`
+- Eleventy: `npx @11ty/eleventy` then `shiply publish _site`
+- MkDocs: `mkdocs build` then `shiply publish site`
+- Hexo: `npx hexo generate` then `shiply publish public`
+- SolidStart (static): `npm run build` then `shiply publish dist/public`
+- Qwik City (static adapter): `npm run build` then `shiply publish dist`
+- Anything else with a built `dist/`/`build/`/`out/`/`_site/`/`public/`/
+  `.output/public/` folder: generic fallback picks it up.
+- Plain HTML: `shiply publish .` — no build step.
+Override auto-detection with `--framework=<name>`. Use the CLI (not inline
+MCP files) for builds — hashed bundles often exceed the 50-file inline cap,
+and the CLI hash-skips unchanged chunks on updates.
+
+## Limits & references
+≤1000 files/site (≤50 inline via MCP), ≤100 MiB/file, 1 GiB total.
+Machine guide: https://shiply.now/llms.txt · OpenAPI:
+https://shiply.now/openapi.json · Docs: https://shiply.now/docs