td-ai-tools 1.4.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/README.md

@@ -7,6 +7,7 @@
 - `browser-validation`: Before completing a task validate frontend or template changes in a real browser with the Playwright-CLI…
 - `cache-reset`: Clear and warm Laravel and Statamic caches (including Statamic Glide image caches) after content or template…
 - `client-overview`: Generate a client-facing markdown report that summarizes all changes on the current branch against the…
+- `cloudflare`: Operate Theory Digital's Cloudflare-hosted sites (Leyline / Astro on Workers) with wrangler and the…
 - `debugging-ios-webkit`: Debugs iOS Safari/Chrome-iOS rendering bugs — stale paints, viewport/browser-chrome clipping, mobile-only CSS…
 - `forge-cli`: Manage Laravel Forge organizations, servers, sites, and provisioned resources with Forge CLI 2.x, falling…
 - `horizon-component-migration`: Bundle Shopify Horizon components into a migration package for a different theme, including recursive…

package/skills/cloudflare/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: cloudflare
+version: 1.0.0
+description: Operate Theory Digital's Cloudflare-hosted sites (Leyline / Astro on Workers) with wrangler and the Cloudflare API — launch a new site end to end, deploy and roll back, preview branches, manage secrets, D1/KV/R2, custom domains and DNS, zone settings (AI crawlers, redirects, caching, SSL), Turnstile, email routing, logs, CI/CD, account/profile switching, client handoff and decommissioning. Use this whenever the user mentions Cloudflare, wrangler, Workers, deploying/shipping/publishing a site, going live, a domain or DNS change, a rollback, a secret or env var, D1 migrations, "the site is down/500ing", tailing logs, or moving a site to a client's account — even if they don't say "Cloudflare" explicitly.
+---
+
+# Cloudflare sites
+
+Theory Digital sites are Astro apps using the Leyline integration, built with `@astrojs/cloudflare` and deployed as **Workers with static assets** (not Pages). Some sites live in the Theory Digital account, some in the client's own account. This skill is the operating manual: SKILL.md gives the ground rules and routes you to one focused reference file per task.
+
+## 1. Orient before acting (always)
+
+Run the read-only preflight from the site's root. It reports wrangler version, who is logged in, the active auth profile, the Worker name, `account_id`, routes/domains, bindings, and git state:
+
+```bash
+bash <skill-dir>/scripts/preflight.sh [site-dir]
+```
+
+From that output, answer three questions before any remote write:
+
+1. **Which account?** The config's `account_id` (or the profile bound to this directory) must match the client this site belongs to. A mismatch is the most damaging mistake available here: it can create a duplicate Worker, or attach a domain, in the wrong client's account. If `account_id` is missing and the login can see more than one account, stop and set it. See `references/auth-and-accounts.md`.
+2. **Which Worker / environment?** Read `name` and any `env.*` blocks. `--env staging` deploys a *different* Worker (`<name>-staging`).
+3. **Is the tree clean and built from the right commit?** Deploying uncommitted work makes the deploy hard to reproduce or roll back to.
+
+## 2. Guardrails: confirm production writes
+
+Do the following freely. They only read, or only touch local or preview resources:
+`whoami`, `deployments list/status`, `versions list/view`, `tail`, `d1 ... --local`, `d1 execute --remote` with a SELECT, `secret list`, `deploy --dry-run`, `wrangler preview`, `astro build`, `wrangler dev`, any `GET` through `cf-api.sh`, and `verify-site.sh`.
+
+**Before** the following, state what will happen (account, Worker or zone, and the exact command) and get a yes from the user:
+- `wrangler deploy` or `versions deploy` to production, and `rollback`
+- `d1 migrations apply --remote`, `d1 execute --remote` that writes, `d1 time-travel restore`
+- `secret put/delete/bulk` against a deployed Worker
+- Creating, changing or deleting DNS records, zone settings, rules, custom domains or routes (any non-GET `cf-api.sh` call)
+- Any `delete` (Worker, D1, KV, R2, Turnstile widget, zone)
+
+Approval covers the action that was described, not similar actions later in the session. If the user has said up front "deploy it, don't ask", that counts as approval for that deploy.
+
+Why the line falls here: everything in the second list is visible to the client's visitors or hard to undo. D1 writes and DNS deletions in particular have no undo button: D1 Time Travel exists but restores the *whole* database.
+
+## 3. Route to the right reference
+
+Read only the file for the task at hand. Each one is self-contained.
+
+| Task | Read |
+|---|---|
+| Launch a brand-new site (repo → live on its domain) | `references/launch-new-site.md` |
+| Deploy, gradual rollout, preview a branch, roll back, check what's live | `references/deploy-and-release.md` |
+| Login, auth profiles, multiple accounts, API tokens, token permissions | `references/auth-and-accounts.md` |
+| Custom domains, routes, adding a zone, nameservers, DNS records, www ↔ apex | `references/domains-and-dns.md` |
+| Zone settings: AI crawlers / bot blocking, redirects, cache rules, SSL/TLS, HSTS, security | `references/zone-settings.md` |
+| Secrets, vars, `.dev.vars`, environments (staging/prod), `wrangler.jsonc` structure | `references/config-secrets-envs.md` |
+| D1 (create, migrate, query, back up, restore), KV, R2 media buckets | `references/data-d1-kv-r2.md` |
+| Forms stack: Postmark, Turnstile widgets, Email Routing, SPF/DKIM/DMARC | `references/forms-email-turnstile.md` |
+| Logs, tailing, observability, analytics, "the site is down" triage | `references/observability-and-incidents.md` |
+| GitHub Actions / Workers Builds, per-PR previews, CI tokens | `references/ci-cd.md` |
+| Inventory/audit across accounts, hand a site to a client's account, decommission, wrangler/compat-date upgrades | `references/site-lifecycle.md` |
+| A specific error message or odd behaviour | `references/troubleshooting.md` |
+
+When a task spans several areas (a launch touches nearly all of them), follow the primary file. It points to the others at the step where they become relevant.
+
+## 4. Bundled tools
+
+- `scripts/preflight.sh [dir]`: read-only orientation report (above).
+- `scripts/cf-api.sh METHOD PATH [JSON]`: thin `curl` wrapper for the Cloudflare REST API. It is used for anything wrangler can't do: zones, DNS, zone settings, rulesets, bot management. It reads `CLOUDFLARE_API_TOKEN` (and `CLOUDFLARE_ACCOUNT_ID` for the `{account}` placeholder), and prints the JSON body or a readable error. Run it with no arguments for usage. Reference examples pipe its output through `jq`. If `jq` isn't installed, suggest `sudo apt install jq` (or `brew install jq`), or filter with `node -e` in the meantime.
+- `scripts/verify-site.sh https://domain [--md /about.md]`: read-only post-deploy smoke test covering status codes, HTTPS/www redirects, robots.txt AI-crawler group, llms.txt, sitemap, the Markdown twin, the form token endpoint, and security headers.
+- `assets/wrangler.jsonc`: annotated starting config for a new Leyline site.
+- `assets/deploy.yml`: GitHub Actions workflow (preview on PR, deploy on main).
+
+## 5. Working conventions
+
+- **Build, then deploy.** `npx astro build` writes `dist/server/wrangler.json` and a redirect at `.wrangler/deploy/config.json`. A plain `npx wrangler deploy` from the site root then deploys the *built* config. Running `wrangler deploy` without a fresh build ships stale output. Don't pass `-c wrangler.jsonc` to deploy, because that bypasses the built config.
+- **Use the project's wrangler** (`npx wrangler`, pinned in `package.json`), not a global one. Flags differ between versions. If a flag in these references is rejected, run `npx wrangler <cmd> --help` and trust that over this skill.
+- **Tag deploys** with `--tag "$(git rev-parse --short HEAD)" --message "<what changed>"`. The tag and message show up in `deployments list` and make rollbacks legible.
+- **Never print secret values** into the transcript. Pipe them in (`printf %s "$VAL" | npx wrangler secret put NAME`) and generate random ones with `openssl rand -base64 48`. Don't echo `CLOUDFLARE_API_TOKEN`.
+- **Prefer config over clicks.** Whatever can live in `wrangler.jsonc` (routes, custom domains, bindings, observability, vars) should, so the repo describes the site. Use the API or dashboard only for zone-level things.
+- **Report what happened**: the deployed version ID, the URL, and what `verify-site.sh` showed. If a step was skipped or failed, say so plainly.
+- Cloudflare's docs are large and change often. When you need something not covered here, fetch the product's `llms.txt` (e.g. `https://developers.cloudflare.com/workers/llms.txt`) rather than guessing.

package/skills/cloudflare/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Cloudflare"
+  short_description: "Deploy and operate Leyline/Astro sites on Cloudflare Workers"
+  default_prompt: "Use $cloudflare to check this site's Cloudflare account, Worker and deploy state before making changes."

package/skills/cloudflare/assets/deploy.yml

@@ -0,0 +1,71 @@
+# Deploy a Leyline site to Cloudflare Workers.
+#   PR    → upload a version with a preview alias (production untouched) and comment the URL
+#   main  → apply D1 migrations (if any) and deploy to production
+# Repo secrets: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, NPM_TOKEN (read access to @theory-digital)
+name: Deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: deploy-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+  pull-requests: write
+
+env:
+  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Check
+        run: npx astro check
+
+      - name: Build
+        run: npx astro build
+
+      - name: Preview (pull request)
+        if: github.event_name == 'pull_request'
+        id: preview
+        run: |
+          npx wrangler versions upload \
+            --preview-alias "pr-${{ github.event.number }}" \
+            --tag "${GITHUB_SHA::7}" \
+            --message "PR #${{ github.event.number }}" | tee upload.log
+          url=$(grep -oE 'https://pr-${{ github.event.number }}-[^ ]+\.workers\.dev' upload.log | head -1)
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+
+      - name: Comment preview URL
+        if: github.event_name == 'pull_request' && steps.preview.outputs.url != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr comment ${{ github.event.number }} --edit-last --create-if-none \
+            --body "Preview: ${{ steps.preview.outputs.url }} (shares production bindings, so form submissions are real)"
+
+      - name: Migrate D1
+        if: github.event_name == 'push' && hashFiles('migrations/*.sql') != ''
+        run: npx wrangler d1 migrations apply DB --remote
+
+      - name: Deploy
+        if: github.event_name == 'push'
+        run: npx wrangler deploy --tag "${GITHUB_SHA::7}" --message "$(git log -1 --pretty=%s | cut -c1-100)"

package/skills/cloudflare/assets/wrangler.jsonc

@@ -0,0 +1,57 @@
+// Starting config for a Leyline site on Cloudflare Workers.
+// Replace every <PLACEHOLDER>. Don't set "main" or "assets": @astrojs/cloudflare generates them
+// into dist/server/wrangler.json at build time, and `wrangler deploy` reads that file.
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "<client>-site",
+  // Pins every wrangler command in this repo to the right account (wrangler whoami lists IDs).
+  "account_id": "<ACCOUNT_ID>",
+  // Pin it and bump it deliberately (see site-lifecycle.md).
+  "compatibility_date": "<YYYY-MM-DD>",
+
+  // Phase 9 of the launch: uncomment once the zone is active on Cloudflare.
+  // "routes": [
+  //   { "pattern": "<domain>", "custom_domain": true },
+  //   { "pattern": "www.<domain>", "custom_domain": true }
+  // ],
+  // Set to false after launch if a public *.workers.dev copy isn't wanted.
+  "workers_dev": true,
+  // Per-version / per-branch preview URLs (deploy-and-release.md → Preview a branch).
+  "preview_urls": true,
+
+  // Workers Logs: persisted, searchable logs in the dashboard.
+  "observability": { "enabled": true, "head_sampling_rate": 1 },
+
+  "vars": {
+    // Turnstile sitekey (public). Remove if the site has no Turnstile.
+    "PUBLIC_TURNSTILE_SITE_KEY": "<SITEKEY>"
+  },
+  // Secrets (never in this file): FORM_SIGNING_SECRET, POSTMARK_SERVER_TOKEN, TURNSTILE_SECRET_KEY
+  //   local: .dev.vars    production: npx wrangler secret put NAME
+
+  // Forms with `persist`: store submissions. `npx wrangler d1 create <client>-site --location enam`
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "<client>-site",
+      "database_id": "<DATABASE_ID>",
+      "migrations_dir": "migrations"
+    }
+  ],
+
+  // Forms with `rateLimit`. namespace_id: any integer unique among this account's sites.
+  "ratelimits": [
+    { "name": "FORM_RATE_LIMITER", "namespace_id": "<1001>", "simple": { "limit": 5, "period": 60 } }
+  ]
+
+  // Optional staging Worker. Bindings and vars do NOT inherit, so repeat them here.
+  // "env": {
+  //   "staging": {
+  //     "name": "<client>-site-staging",
+  //     "routes": [{ "pattern": "staging.<domain>", "custom_domain": true }],
+  //     "vars": { "PUBLIC_TURNSTILE_SITE_KEY": "<SITEKEY>" },
+  //     "d1_databases": [{ "binding": "DB", "database_name": "<client>-site-staging", "database_id": "<ID>", "migrations_dir": "migrations" }],
+  //     "ratelimits": [{ "name": "FORM_RATE_LIMITER", "namespace_id": "<1002>", "simple": { "limit": 5, "period": 60 } }]
+  //   }
+  // }
+}

package/skills/cloudflare/references/auth-and-accounts.md

@@ -0,0 +1,62 @@
+# Auth and accounts
+
+Theory Digital has a mixed setup: most sites run in the Theory Digital account, and some in accounts the client owns, with TD as a member. Two separate credentials are involved:
+
+| Credential | Used by | Covers |
+|---|---|---|
+| **Wrangler OAuth login** (per profile) | `wrangler …` | Workers, D1, KV, R2, secrets, Turnstile, routes/custom domains |
+| **API token** (`CLOUDFLARE_API_TOKEN`) | `scripts/cf-api.sh`, CI, and wrangler too when set | Anything with matching permissions, including zone settings and DNS, which wrangler can't touch |
+
+When `CLOUDFLARE_API_TOKEN` is set in the environment, **wrangler uses it instead of the OAuth login**. Most "wrong account", "Authentication error [code: 10000]" and "permission denied" confusion comes from a stale token in the shell. Check `env | grep CLOUDFLARE_` first.
+
+## Wrangler login and profiles
+
+```bash
+npx wrangler whoami                    # who, which accounts, token scopes
+npx wrangler login                     # default profile, browser OAuth
+```
+
+Named profiles (experimental in wrangler 4.14x, but they work well for mixed accounts):
+```bash
+npx wrangler auth create td                    # TD staff login
+npx wrangler auth create client-acme           # a login that can see Acme's account
+npx wrangler auth activate client-acme ~/sites/acme   # bind a directory → profile
+npx wrangler auth list
+npx wrangler deploy --profile td               # one-off override
+```
+Even with a profile bound, still set `account_id` in `wrangler.jsonc`. A login that can see several accounts would otherwise prompt interactively, and in CI it would fail.
+
+**WSL / headless login**: the OAuth callback goes to `localhost:8976`. In WSL2 the browser usually opens on Windows and the callback works. If it doesn't, copy the printed URL into a browser manually. If that callback fails too, use an API token instead.
+
+**Account selection**: `npx wrangler whoami` lists account names and IDs. When the user names a client, match the name in that list and confirm the ID with them before writing it to the config. Similar names (e.g. "Acme" vs "Acme Holdings") are common.
+
+## API tokens for `cf-api.sh` and CI
+
+Create tokens at dash.cloudflare.com → My Profile → API Tokens (user-owned), or in the account under Manage Account → Account API Tokens (account-owned; better for CI because it survives staff leaving). Scope each one to a single account and only the zones it needs.
+
+Recommended permission sets:
+
+**Site operator token** (used interactively with this skill):
+- Account: Workers Scripts Edit · D1 Edit · Workers KV Storage Edit · Workers R2 Storage Edit · Turnstile Sites Edit · Account Settings Read
+- Zone (specific zones, or all zones in the account): Zone Read · DNS Edit · Zone Settings Edit · Workers Routes Edit · Bot Management Edit · Dynamic URL Redirects Edit (Single Redirects) · Cache Rules Edit · Email Routing Rules Edit · SSL and Certificates Edit
+- Adding new zones needs **Zone: Edit** at the account level. Grant it only to tokens that launch sites.
+
+**CI deploy token** (deploys only): Account: Workers Scripts Edit, D1 Edit (if CI applies migrations), Account Settings Read. Zone: Workers Routes Edit (for custom domains/routes in the config). Nothing else.
+
+Permission names in the dashboard shift over time. If a call returns `10000 Authentication error` or `9109 Unauthorized`, compare the endpoint with the token's permission list rather than retrying.
+
+Verify a token without printing it:
+```bash
+bash scripts/cf-api.sh GET /user/tokens/verify                       # user-owned token
+bash scripts/cf-api.sh GET /accounts/{account}/tokens/verify          # account-owned token
+bash scripts/cf-api.sh GET '/zones?per_page=50'                       # which zones it sees
+```
+
+Keeping the token out of the transcript: ask the user to `export CLOUDFLARE_API_TOKEN=…` in their own shell (`! export …` in Claude Code), or to store it in a gitignored file you `source`. Never put it in `wrangler.jsonc`, the repo, or a command line you echo.
+
+## Clients' own accounts
+
+- Ask the client to invite a Theory Digital address as a **member** with a role that covers Workers and zones ("Administrator", or narrower roles such as "Workers Admin" plus "DNS"). Avoid having them share their own login.
+- For CI on the client's account, create an **account-owned token** in *their* account, so it doesn't depend on any one TD staff member.
+- Billing: Workers Paid, Turnstile and so on are billed to whichever account owns the resource. Confirm the plan before enabling paid features in a client's account.
+- Moving a site between accounts: see `site-lifecycle.md`.

package/skills/cloudflare/references/ci-cd.md

@@ -0,0 +1,48 @@
+# CI/CD
+
+There are two ways to deploy automatically. Pick one per site; using both causes double deploys.
+
+| | GitHub Actions (`assets/deploy.yml`) | Workers Builds (Cloudflare's Git integration) |
+|---|---|---|
+| Setup | Workflow file plus repo secrets | Connect the repo in the dashboard (Worker → Settings → Builds) |
+| Runs | In GitHub, with your own test steps | In Cloudflare's build environment |
+| PR previews | Via `versions upload --preview-alias`, commented on the PR | Built in (non-production branch builds get preview URLs) |
+| Migrations / secrets | Scriptable in the workflow | Build command only. Migrations remain a manual step |
+| Good for | Sites with lint/tests, D1 migrations, or anything custom | Simple sites where the client account owner wants it all in Cloudflare |
+
+The Theory Digital default is **GitHub Actions**: it runs the same `astro check`/build as local, and the account and token are explicit.
+
+## GitHub Actions setup
+
+1. Copy `assets/deploy.yml` from this skill to `.github/workflows/deploy.yml` in the site repo. Adjust the Node version and the site's check script.
+2. Create a **CI deploy token** in the account that owns the Worker. Permissions are in `auth-and-accounts.md`; an account-owned token is best.
+3. Add repo secrets (the user does this in GitHub, or with `gh secret set` after confirming with them):
+   ```bash
+   gh secret set CLOUDFLARE_API_TOKEN          # prompts for the value, keeping it out of shell history
+   gh secret set CLOUDFLARE_ACCOUNT_ID --body "<account id>"
+   ```
+4. Protect `main`, so that what deploys has passed review.
+5. On the first CI deploy, watch it with `gh run watch` and then run `verify-site.sh`.
+
+What the workflow does:
+- **Pull request** → build → `wrangler versions upload --preview-alias pr-<n>` → comment with the preview URL. Production is untouched. This needs `"preview_urls": true` in `wrangler.jsonc`.
+- **Push to main** → build → `d1 migrations apply --remote` (only if a `migrations/` dir exists) → `wrangler deploy --tag <sha>`.
+
+Adding CI to a repo is a code change to the site. The deploys it then performs were authorized by merging. You don't need to confirm each CI run.
+
+## Secrets in CI
+
+Worker runtime secrets (`FORM_SIGNING_SECRET` etc.) stay on the Worker. Set them once with `wrangler secret put`, and CI never sees them. Only `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` go into GitHub.
+
+## Workers Builds notes
+
+- Build command: `npx astro build`. Deploy command: `npx wrangler deploy`. Non-production branch deploy command: `npx wrangler versions upload`.
+- Builds run in the account that owns the Worker, so the client's account needs the Git connection authorized there. For client-owned accounts, the client may need to approve the GitHub app.
+- Inspect builds in the dashboard. There's no first-class wrangler command for build logs.
+
+## Troubleshooting CI
+
+- `Authentication error [code: 10000]` → wrong token, token scoped to another account, or a missing permission.
+- `More than one account available` → set `CLOUDFLARE_ACCOUNT_ID` (or `account_id` in the config).
+- Deploy succeeds but the site is unchanged → CI deployed a stale build, or deployed to a different Worker name/env. Compare `deployments list` author and tag.
+- `npm ci` fails on a private package → `@theory-digital/leyline` is restricted on npm. CI needs `NODE_AUTH_TOKEN` with read access and an `.npmrc` (`//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`). The workflow template includes this.

package/skills/cloudflare/references/config-secrets-envs.md

@@ -0,0 +1,55 @@
+# Config, secrets and environments
+
+## Where each kind of value lives
+
+| Kind | Example | Where | In git? |
+|---|---|---|---|
+| Bindings | D1, KV, R2, ratelimits | `wrangler.jsonc` | yes |
+| Public/plain vars | `PUBLIC_TURNSTILE_SITE_KEY` | `wrangler.jsonc` → `vars` | yes |
+| Secrets | `FORM_SIGNING_SECRET`, `POSTMARK_SERVER_TOKEN`, `TURNSTILE_SECRET_KEY` | `wrangler secret put` (prod), `.dev.vars` (local) | **no** |
+| Build-time site config | `site.url`, locales, forms | `astro.config.ts` (`leyline({...})`) | yes |
+
+Leyline reads these through `astro:env`. A var or secret missing at runtime shows up as a startup or first-request error naming the key (see `troubleshooting.md`).
+
+## `wrangler.jsonc` essentials
+
+The adapter merges the site's `wrangler.jsonc` into `dist/server/wrangler.json` at build time, adding `main`, `assets`, a `SESSION` KV binding and an `IMAGES` binding. Edit the source file only. The `dist/` copy is regenerated.
+
+Keys worth knowing (the template in `assets/wrangler.jsonc` is annotated):
+- `name`: the Worker. Renaming it creates a **new** Worker; the old one keeps running on its domains until deleted.
+- `account_id`: pin it. See `auth-and-accounts.md`.
+- `compatibility_date`: when it's omitted, the adapter sets one at build. Pin it explicitly for reproducible builds, and bump it deliberately (`site-lifecycle.md`).
+- `routes`, `workers_dev`, `preview_urls`: see `domains-and-dns.md` and `deploy-and-release.md`.
+- `observability`: `{ "enabled": true }` turns on Workers Logs (`observability-and-incidents.md`).
+- `vars`: wiped and replaced on every deploy unless `--keep-vars` is passed.
+
+## Secrets
+
+```bash
+npx wrangler secret list                                    # names only, values are never readable
+printf %s "$VALUE" | npx wrangler secret put NAME           # (confirm), creates a new deployment immediately
+npx wrangler secret delete NAME                             # (confirm)
+npx wrangler secret bulk secrets.json                       # (confirm) {"A":"…","B":"…"}; "B": null deletes in JSON form
+```
+- `secret put` **deploys immediately**, so it counts as a production change. Under gradual deployments, use `npx wrangler versions secret put` instead, which creates a version without deploying it.
+- Values never appear in the transcript. Generate with `openssl rand -base64 48`, read from `.dev.vars`, or ask the user to run `! printf %s 'value' | npx wrangler secret put NAME` themselves. For bulk files, write to the scratchpad, upload, then delete the file.
+- `wrangler deploy --secrets-file <file>` uploads secrets together with the code in one version. It's additive: omitted secrets are kept.
+- **Rotation** of `FORM_SIGNING_SECRET`: tokens already issued to open tabs stop validating, and those visitors see a retry. Do it at a quiet time. To rotate `POSTMARK_SERVER_TOKEN`, create the new token in Postmark → `secret put` → test a submission → revoke the old one.
+- "Is secret X set?": `secret list`. To check a value, compare behaviour, e.g. a form submission works. You can't read the value back.
+
+## `.dev.vars` (local)
+
+Gitignored, `KEY=value` per line, read by `wrangler dev` and `astro dev`. For environments, `.dev.vars.staging` is used with `--env staging`. Keep a committed `.dev.vars.example` that lists the keys without values, so a new developer knows what's needed.
+
+Leyline test helper: `POSTMARK_API_URL` points form delivery at a mock server. It only belongs in local or test configs, never in production.
+
+## Environments
+
+See `deploy-and-release.md` → Staging for the full pattern. Key rules:
+- `--env X` targets Worker `<name>-X` (or `env.X.name` if set).
+- **Non-inheritable keys** have to be repeated inside each env: `vars`, `d1_databases`, `kv_namespaces`, `r2_buckets`, `ratelimits`, `routes`, and the other bindings. Top-level `name`, `account_id`, `compatibility_date` and `observability` are inherited.
+- Secrets are per-Worker, so `secret put NAME --env staging` is separate from production.
+
+## Types
+
+`npx wrangler types` generates `worker-configuration.d.ts` from the config, which gives typed `env` bindings. Run it after adding bindings. Leyline sites usually rely on `astro:env`, so it's optional.

package/skills/cloudflare/references/data-d1-kv-r2.md

@@ -0,0 +1,96 @@
+# Data: D1, KV, R2
+
+## Contents
+- D1: create, migrate, query, export/backup, Time Travel restore, delete
+- Form submissions: common queries
+- EmDash on D1
+- KV
+- R2 (media, uploads, backups)
+
+---
+
+## D1
+
+```bash
+npx wrangler d1 list
+npx wrangler d1 info acme-site                         # size, region, tables
+npx wrangler d1 create acme-site --location enam       # (confirm) also --jurisdiction eu|us|fedramp for data residency (permanent)
+```
+
+### Migrations
+Files go in `migrations/NNNN_name.sql` (`migrations_dir` in the config). Applied state is tracked in the `d1_migrations` table.
+```bash
+npx wrangler d1 migrations list DB --remote            # what's pending
+npx wrangler d1 migrations create DB add_x             # new empty file with the next number
+npx wrangler d1 migrations apply DB --local            # dev
+npx wrangler d1 migrations apply DB --remote           # (confirm). Takes a backup bookmark first, rolls back a failing file
+```
+- Write migrations **additively** (add columns or tables; don't drop or rename in the same release as the code change). Rollbacks then stay safe, and a deploy window where old code runs against the new schema is harmless.
+- Run remote migrations **before** deploying code that needs them.
+- When Leyline adds a migration in a new version, copy the new file(s) from `node_modules/@theory-digital/leyline/src/forms/migrations/` into the site's `migrations/` as part of the Leyline upgrade.
+
+### Querying
+```bash
+npx wrangler d1 execute DB --remote --command "SELECT count(*) FROM leyline_submissions"
+npx wrangler d1 execute DB --remote --file ./query.sql
+npx wrangler d1 execute DB --remote --json --command "…"     # machine-readable output
+```
+Read-only queries are fine without asking. `INSERT/UPDATE/DELETE/DROP/ALTER` against `--remote` need confirmation. Show the exact SQL, and show a `SELECT count(*)` with the same `WHERE` clause first, so the user sees how many rows will change.
+
+### Backup / export
+```bash
+npx wrangler d1 export DB --remote --output backups/acme-$(date +%F).sql            # full
+npx wrangler d1 export DB --remote --no-data --output schema.sql                    # schema only
+```
+Exports can contain personal data (form submissions). Keep them out of git, and delete local copies when done.
+
+### Time Travel (point-in-time restore, last 30 days)
+```bash
+npx wrangler d1 time-travel info DB --timestamp 2026-10-01T12:00:00Z    # get the bookmark for that moment
+npx wrangler d1 time-travel restore DB --timestamp 2026-10-01T12:00:00Z  # (confirm), overwrites the WHOLE database
+```
+A restore rewinds every table, including legitimate submissions received since then. Before a restore, export the current state, so lost rows can be re-inserted selectively. The restore prints a bookmark for the pre-restore state; record it, because it makes the restore itself undoable.
+
+### Delete
+`npx wrangler d1 delete acme-site` (confirm, and export first). Remove the binding from the config, or the next deploy fails.
+
+## Form submissions: common queries
+
+```sql
+-- recent
+SELECT form, locale, status, created_at FROM leyline_submissions ORDER BY created_at DESC LIMIT 20;
+-- delivery failures (Postmark errors)
+SELECT id, form, error, created_at FROM leyline_submissions WHERE status = 'failed' ORDER BY created_at DESC;
+-- volume per day
+SELECT substr(created_at,1,10) AS day, count(*) FROM leyline_submissions GROUP BY day ORDER BY day DESC LIMIT 30;
+-- spam-flagged
+SELECT created_at, flags FROM leyline_submissions WHERE flags <> '[]' ORDER BY created_at DESC LIMIT 20;
+```
+`data` holds the submitted fields as JSON (`json_extract(data, '$.email')`). It's personal data, so don't dump whole rows into the chat unless the user asks for specific records. Privacy or erasure requests: `DELETE FROM leyline_submissions WHERE json_extract(data,'$.email') = ?` (confirm, after a count).
+
+## EmDash on D1
+
+Production EmDash sites use `@emdash-cms/cloudflare`'s `d1()` driver (see Leyline's `docs/CONTENT-MODEL.md`). They usually have a separate D1 database for CMS content, apart from form submissions; that keeps exports and restores scoped. Content seeding: `leyline-seed` generates seed JSON from a static site, and EmDash's CLI applies it. Treat a content-DB restore as an editor-visible event and tell the client.
+
+## KV
+
+```bash
+npx wrangler kv namespace list
+npx wrangler kv namespace create acme-cache                           # (confirm) → paste id into kv_namespaces
+npx wrangler kv key list --binding SESSION --remote | head
+npx wrangler kv key get --binding X "key" --remote
+npx wrangler kv key put --binding X "key" "value" --remote            # (confirm)
+```
+The Astro adapter adds a `SESSION` KV binding, used by Astro sessions. Wrangler auto-provisions it on first deploy when it has no ID. If a site doesn't use sessions, it's harmless.
+
+## R2
+
+Use it for media too big or too dynamic for the repo (EmDash uploads, video, downloadable PDFs), or as a backup target.
+```bash
+npx wrangler r2 bucket list
+npx wrangler r2 bucket create acme-media                               # (confirm), add --jurisdiction eu if needed
+npx wrangler r2 bucket domain add acme-media --domain media.acme.com --zone-id <zone_id>   # (confirm) public custom domain
+npx wrangler r2 object put acme-media/path/file.pdf --file ./file.pdf --remote
+npx wrangler r2 bucket cors set acme-media --file cors.json           # if the browser fetches directly
+```
+Serve public media through a custom domain, not `r2.dev`, which is rate-limited and meant for development. Bind the bucket in `wrangler.jsonc` (`r2_buckets: [{ "binding": "MEDIA", "bucket_name": "acme-media" }]`) if the Worker reads or writes it.

package/skills/cloudflare/references/deploy-and-release.md

@@ -0,0 +1,107 @@
+# Deploy and release
+
+## Contents
+- Standard production deploy
+- What's live right now?
+- Gradual rollout (versions)
+- Preview a branch without touching production
+- Roll back
+- Staging environment
+- Content-only changes (EmDash)
+
+---
+
+## Standard production deploy
+
+```bash
+bash <skill>/scripts/preflight.sh            # account, Worker name, clean tree
+npm run check 2>/dev/null || npx astro check # if the site has a check script; don't deploy type errors
+npx astro build
+npx wrangler deploy --dry-run                # catches config/binding errors, uploads nothing
+npx wrangler deploy --tag "$(git rev-parse --short HEAD)" --message "<one-line summary>"   # (confirm)
+bash <skill>/scripts/verify-site.sh https://<domain>
+```
+
+Notes:
+- `wrangler deploy` from the site root picks up the built config through `.wrangler/deploy/config.json`. If you see "Missing entry-point" or a deploy of the wrong thing, the build didn't run or ran in a different directory.
+- **Vars set in the dashboard are wiped** on deploy unless you pass `--keep-vars`. Secrets are never wiped. If someone added a var by hand, move it into `wrangler.jsonc` rather than relying on `--keep-vars` forever.
+- New D1 migrations? Apply them **before** deploying code that depends on them (`npx wrangler d1 migrations apply DB --remote`, confirm). Migrations should be additive, so the old code keeps working against the new schema during the window between the two steps.
+- The deploy output prints the **Version ID** and URLs. Capture the Version ID for the report and for any rollback.
+
+## What's live right now?
+
+```bash
+npx wrangler deployments status      # the active deployment: version(s) and traffic split
+npx wrangler deployments list        # last 10 deployments with tag, message, author, time
+npx wrangler versions list           # uploaded versions (including undeployed ones)
+npx wrangler versions view <id>      # one version's bindings, compat date, etc.
+```
+Compare the deployed tag with `git log --oneline` to see what's unreleased.
+
+## Gradual rollout (versions)
+
+Use this for risky changes on busy sites: a new form flow, a dependency upgrade, a compat-date bump.
+
+```bash
+npx astro build
+npx wrangler versions upload --tag "$(git rev-parse --short HEAD)" --message "..."   # uploads, no traffic. Prints a version ID and a preview URL
+# test the version preview URL
+npx wrangler versions deploy <new-id>@10% <current-id>@90% --message "canary"   # (confirm)
+npx wrangler tail --version-id <new-id> --status error                           # watch for errors
+npx wrangler versions deploy <new-id>@100% --message "full rollout"              # (confirm)
+```
+Things to know:
+- A visitor can land on different versions on successive requests unless session affinity is configured. For a marketing site that's fine. Avoid splits on changes where the HTML and its form endpoint must match exactly. Leyline form tokens are validated by the shared secret, not by the version, so forms survive splits.
+- Static assets belong to the version that serves them.
+- Changes to routes, custom domains or cron triggers are **not** carried by `versions upload`. Apply them with `npx wrangler triggers deploy`, or do a normal `wrangler deploy`.
+
+## Preview a branch without touching production
+
+Two mechanisms; choose based on what's needed.
+
+1. **Version preview URLs**, the stable option. Set `"preview_urls": true` in `wrangler.jsonc` (the template does this). Then:
+   ```bash
+   npx wrangler versions upload --preview-alias "$(git branch --show-current | tr '/_' '--' | cut -c1-40)"
+   ```
+   This gives `https://<alias>-<worker>.<subdomain>.workers.dev`. The preview shares production bindings, so **form submissions hit the real D1 and send real email**. Warn the user, or point Postmark at a test server for previews. The alias URL stays stable across uploads on the same branch.
+
+2. **`wrangler preview`** (open beta). It creates a named Preview (defaulting to the git branch) with its own deployments and its own secrets (`wrangler preview secret put`). It uses the Preview base config from the dashboard unless you pass `--ignore-base-config`. It isolates secrets better, but it's beta: check `npx wrangler preview --help`, and expect behaviour to change.
+
+Previews aren't "production writes" in the guardrail sense, so you don't need to ask. Do mention the shared-bindings caveat.
+
+Search engines: workers.dev hosts serve the same robots.txt as production. Canonicals point at the production URL, so duplicate content isn't a real risk.
+
+## Roll back
+
+```bash
+npx wrangler deployments list                         # find the last good version (by tag/time)
+npx wrangler rollback <version-id> -m "reason"        # (confirm). Without an ID it goes to the previous version
+bash <skill>/scripts/verify-site.sh https://<domain>
+```
+What a rollback **does not** undo:
+- **D1 schema or data changes.** If the bad deploy ran a migration, the old code now runs against the new schema. That's fine if the migration was additive; otherwise see `data-d1-kv-r2.md` → Time Travel.
+- **Secrets changed since then.** Rollback restores the code and its config bindings, but secrets are whatever is current.
+- Zone settings, DNS, and redirect rules. Those aren't part of the Worker.
+
+After a rollback, the next normal `wrangler deploy` replaces it. Make sure the fix is in before you deploy again, or the bad code ships again.
+
+## Staging environment
+
+Optional. Use it for clients who want sign-off before production. In `wrangler.jsonc`:
+```jsonc
+"env": {
+  "staging": {
+    "name": "acme-site-staging",           // explicit is clearer than the implicit suffix
+    "routes": [{ "pattern": "staging.acme.com", "custom_domain": true }],
+    "vars": { "PUBLIC_TURNSTILE_SITE_KEY": "1x00000000000000000000AA" },
+    "d1_databases": [{ "binding": "DB", "database_name": "acme-site-staging", "database_id": "…", "migrations_dir": "migrations" }]
+  }
+}
+```
+Bindings and vars **don't inherit** into an env; repeat them there. Deploy with `npx wrangler deploy --env staging`, which counts as a production-style write to the staging Worker (confirm, but it's low stakes). Secrets are per-Worker: `npx wrangler secret put NAME --env staging`.
+
+Protect staging from the public and from search engines with Cloudflare Access (Zero Trust → Access → application on `staging.acme.com`). That's a dashboard step.
+
+## Content-only changes (EmDash)
+
+EmDash sites serve content from D1 at request time. Editors publishing in the EmDash admin don't need a deploy. A deploy is only needed for code, template or config changes. If an editor says "my change isn't showing", look at caching (`zone-settings.md` → Cache rules) and the EmDash publish state before redeploying.