vybekiit 0.7.19 → 0.7.21

package/dist/global-skills/neon/SKILL.md

@@ -9,7 +9,12 @@ description: >-
   are the trigger: "object storage" or "S3", "buckets", "serverless functions",
   "AI gateway", "call an LLM", "logs", "branch logs", "query logs",
   "log export", "Loki", "Grafana", "observability", "telemetry", "postgres",
-  "database", or "backend".
+  "database", or "backend". Also use when there is no Neon account yet, the
+  user cannot sign in or provide an API key right now and needs a project they
+  can claim later, or the user asks for a throwaway DATABASE_URL, Claimable Neon,
+  Claimable Postgres, neon.new, claimable.neon.tech, instant Postgres, a no-signup
+  database, temporary postgres, quick postgres, a no credit card database, or
+  npx neon-new.
 metadata:
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon
 ---
@@ -79,15 +84,14 @@ Neon provides a set of agent skills in addition to the official documentation. W
 
 The skills below live in the [`neondatabase/agent-skills`](https://github.com/neondatabase/agent-skills) repo:
 
-| Skill | Use it for |
-| --- | --- |
-| `neon-postgres` | Working with databases, including connections, schemas, queries, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions. |
-| `neon-postgres-branches` | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command. |
-| `neon-object-storage` | Storing and serving files (uploads, images, blobs), including branching them with the database. |
-| `neon-functions` | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers. |
-| `neon-ai-gateway` | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. |
-| `claimable-postgres` | Provisioning instant, claimable temporary Postgres databases (for example, one per end user or demo). |
-| `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase. |
+| Skill                            | Use it for                                                                                                                                                                           |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `neon-postgres`                  | Working with databases, including connections, schemas, queries, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions.                   |
+| `neon-postgres-branches`         | Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command.                                                               |
+| `neon-object-storage`            | Storing and serving files (uploads, images, blobs), including branching them with the database.                                                                                      |
+| `neon-functions`                 | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers.                                                                                      |
+| `neon-ai-gateway`                | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. |
+| `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase.                                                                                          |
 
 For guidance on agent platforms that provision and operate Lakebase Postgres on Neon at scale, use `neon-postgres-agent-platforms`, which lives in a separate repo: [`neondatabase/neon-for-agent-platforms`](https://github.com/neondatabase/neon-for-agent-platforms).
 
@@ -121,6 +125,15 @@ Use the same method that was used to install them. With the `skills` CLI, run th
 
 ## Getting Started with Neon
 
+Before `npx neon@latest init --agent`, check whether the CLI is already authenticated:
+
+- `NEON_API_KEY` is set
+- `npx neon@latest profile list -o json` lists a profile whose `account` is not `-`
+
+A `DEFAULT` row with `account: "-"` and `file: "missing"` is not an account. If `neon` is not installed, or `npx neon@latest profile list` cannot run, that is not an account.
+
+If none of those hold, follow [Starting without a Neon account](#starting-without-a-neon-account).
+
 The easiest way to get started with Neon is to use our CLI and the project bootstrap wizard:
 
 ```bash
@@ -168,6 +181,16 @@ Useful MCP tools to initialize a project:
 - `create_project` — Creates a new Neon project in your Neon account. A project acts as a container for branches, databases, roles, and computes.
 - `get_connection_string` — Returns your database connection string.
 
+## Starting without a Neon account
+
+If the Getting Started account check found credentials, use them. If a command waits on a browser (`Awaiting authentication in web browser`) or authentication fails, stop and ask the user to sign in (`neon auth`) or mint an API key. Prefer that over Claimable Neon unless they say otherwise.
+
+If they cannot sign in or provide a key right now, ask before using Claimable Neon. Continue only after they say yes. That is a temporary workaround.
+
+If there is no Neon account yet, follow [references/claimable-neon.md](https://neon.com/docs/ai/skills/neon/references/claimable-neon.md). Do not run `neon init --agent` or `neon auth` on this path; those need a human Neon account. If `neon claim` is missing, the reference has the REST fallback.
+
+Requests for neon.new, Claimable Postgres, claimable.neon.tech, instant Postgres, or a no-signup database are the same path.
+
 ## Neon Infrastructure as Code
 
 `neon.ts` is Neon's branch config and infrastructure-as-code file: declare which Neon services your project's branches should have, get type-safe env vars, and program branch settings — all in TypeScript. It's the config layer for your Neon services, and it composes with the branch-first loop below. Add it with `@neon/config`:
@@ -208,12 +231,8 @@ export default defineConfig({
   auth: true,
   dataApi: true,
   preview: {
-    functions: {
-      /* ... */
-    }, // see the neon-functions skill
-    buckets: {
-      /* ... */
-    }, // see the neon-object-storage skill
+    functions: {},
+    buckets: {},
     aiGateway: true, // see the neon-ai-gateway skill
   },
 });
@@ -395,7 +414,11 @@ for await (const record of neon.logs.query(projectId, branchId, {
 }
 
 const { data: fields } = await neon.logs.fields(projectId, branchId);
-const { data: serviceNames } = await neon.logs.fieldValues(projectId, branchId, "service_name");
+const { data: serviceNames } = await neon.logs.fieldValues(
+  projectId,
+  branchId,
+  "service_name",
+);
 ```
 
 `query`'s iterator always throws on error, but `fields` and `fieldValues` follow the client's `throwOnError`, which defaults to `false` and hands back `{ data, error }`. `fieldValues` resolves to the whole response, not a bare array: read `serviceNames.values`, and treat them as an arbitrary subset whenever `serviceNames.is_truncated` is true.

package/dist/global-skills/neon/references/claimable-neon.md

@@ -0,0 +1,91 @@
+# Claimable Neon
+
+Claimable Neon provisions a temporary Neon project — Lakebase Postgres, and optionally the Data API and Managed Better Auth — before a human creates an account. The agent holds an identity assertion, not a Neon API key. A human can later claim the project into their organization.
+
+This flow follows the [auth.md](https://claimable.neon.tech/auth.md) protocol. Fetch `https://claimable.neon.tech/auth.md` for request and response fields. REST is on `https://claimable.neon.tech`. Use the table below; do not invent other identity paths.
+
+Use this after the neon skill account check found no account.
+
+## Path
+
+1. Install the CLI: `npm i -g neon@latest`
+2. If `neon claim --help` does not list `create`, skip to [If neon claim is missing](#if-neon-claim-is-missing).
+3. Write a `neon.ts` that declares the services you need, or skip the file and pass `--service` on create. Postgres is always requested.
+4. Create the project: `neon claim create --env-pull` (add `--service data-api --service auth` if there is no `neon.ts`)
+5. If create did not write env, pull it: `neon env pull`
+6. Use the `neon-postgres` skill for connections, schemas, and queries. Install it if it is missing: `neon skills -s neon-postgres`
+
+Do not run `neon init --agent` or `neon auth` on this path; those need a human Neon account. `--api-key` and `--profile` are refused on `neon claim`.
+
+```bash
+npm i -g neon@latest
+neon claim --help
+```
+
+If that help lists `create` and you need Auth or the Data API, `npm i @neon/config` and write `neon.ts`. Then `neon claim create --env-pull`.
+
+```typescript
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  auth: true,
+  dataApi: true,
+});
+```
+
+`neon claim create` reads `neon.ts` when it is present. It writes provisioned vars to an existing `.env`, otherwise `.env.local`, and gitignores that file. If `.env` or `.env.local` already has a `DATABASE_URL` (or other Neon-managed keys), pass `--file <path>` or `--no-env-pull`. The identity assertion is the pre-claim credential.
+
+Before claim, Postgres is always granted; Auth and the Data API are granted when requested. Functions, Object Storage, and AI Gateway come back with `granted: false` and `reason: "requires_claim"`. The CLI prints those as `denied_capabilities`. Report what you were given. Do not retry or strip them.
+
+After create, report the `project_id`, `project_expires_at`, and any denied capabilities. Do not invent the window.
+
+## Claim
+
+Do not mint a claim URL until the human is ready. Opening the URL does not freeze access. Continuing to Neon starts the transfer and rotates `DATABASE_URL`. Existing access tokens are revoked. Auth and the Data API stay enabled when they were granted.
+
+When `reconciled` is true, the pre-claim `DATABASE_URL` no longer works. Auth and Data API URLs stay. The human signs in with `neon auth`. Then the agent runs `neon link --agent` and `neon env pull` to write the new `DATABASE_URL`. `neon link --agent` discovers the project after that sign-in.
+
+### With the CLI
+
+When the human is ready, run `neon claim accept --no-open`. Bare `neon claim accept` opens a browser. Report the `verification_url`, `user_code`, and `expires_in_seconds` the CLI printed (HTTP names: `verification_uri_complete`, `user_code`, `expires_in`). If the code expires, run `neon claim accept --no-open` again. Poll with `neon claim status`. The CLI re-exchanges the assertion; do not call the token endpoint yourself.
+
+```bash
+neon claim accept --no-open
+neon claim status
+```
+
+Permanently delete the unclaimed project (this does not cancel a claim):
+
+```bash
+neon claim delete --yes
+```
+
+### With REST
+
+An agent must not complete the claim. Do not `POST /v1/projects/{id}/claim` until the human is ready. The human opens `verification_uri_complete` and accepts the transfer. If the claim code expires, `POST /v1/projects/{id}/claim` again. The live claim response also includes `user_code` and `expires_in`. `auth.md` documents `verification_uri_complete` and the polling `interval`.
+
+After the human continues to Neon, existing access tokens are revoked: re-exchange the identity assertion, then poll `GET /v1/projects/{id}/claim` with that token at the interval `auth.md` returns. `claim_in_progress` means keep polling with the post-redemption token, not the token from create. Report `verification_uri_complete`, `user_code`, and `expires_in`.
+
+When `error.code` is `capability_requires_claim`, preserve the denied capability and give the human a claim link instead of retrying or silently omitting it.
+
+Only `invalid_grant`, `project_expired`, and `project_claimed` mean the stored identity assertion is dead. `token_expired` means re-exchange the assertion.
+
+## If neon claim is missing
+
+Fall back to the REST API. Fetch `https://claimable.neon.tech/auth.md` for request and response fields. The claimable resource is `/v1/projects/{id}` on `https://claimable.neon.tech`, not `/v1/databases/{id}`. Follow [Claim](#claim) for when to mint, what rotates, and what to do after `reconciled`.
+
+```http
+POST https://claimable.neon.tech/v1/agent/identity
+POST https://claimable.neon.tech/v1/oauth2/token
+GET  https://claimable.neon.tech/v1/projects/{id}/credentials
+POST https://claimable.neon.tech/v1/projects/{id}/claim
+GET  https://claimable.neon.tech/v1/projects/{id}/claim
+DELETE https://claimable.neon.tech/v1/projects/{id}
+```
+
+| CLI                           | REST                                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| `neon claim create`           | `POST /v1/agent/identity`, then `POST /v1/oauth2/token`, then `GET /v1/projects/{id}/credentials` |
+| `neon claim accept --no-open` | `POST /v1/projects/{id}/claim`                                                                    |
+| `neon claim status`           | `GET /v1/projects/{id}/claim`                                                                     |
+| `neon claim delete --yes`     | `DELETE /v1/projects/{id}`                                                                        |

package/dist/global-skills/neon-object-storage/SKILL.md

@@ -10,8 +10,8 @@ description: >-
   Supabase Storage. Triggers include "object storage", "bucket", "blob
   storage", "file storage", "store uploads/images/files", "S3-compatible
   storage", "presigned URL", "where do I put files", "storage logs",
-  "bucket logs", "Neon Object Storage", "Neon Storage", and "storage that
-  branches with my database".
+  "bucket logs", "CDN in front of object storage", "Neon Object Storage",
+  "Neon Storage", and "storage that branches with my database".
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-object-storage
@@ -35,14 +35,14 @@ Use this skill to help the user store and serve files that branch alongside thei
 
 ## When to Use
 
-Reach for Neon Object Storage when the user needs to store files (images, uploads, generated assets, documents, backups) and any of the following are true:
+Reach for Neon Object Storage for the files an app and its users produce — uploads, attachments, avatars, images, documents, generated assets, backups. It is the default place to put them when the app is already on Neon:
 
 - **They already use Lakebase Postgres and don't want a second provider.** One backend, one bill, one CLI, one set of branches — instead of standing up and wiring a separate AWS S3 / R2 / Supabase Storage account. The same Neon credential that backs the database backs storage.
 - **Files must stay in sync with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
 - **They want safe, throwaway environments.** Upload, overwrite, and delete files in a preview/CI branch without any risk to production data, then drop the branch.
 - **They want standard S3 tooling.** It's built on S3 semantics and speaks the S3 API, so the AWS SDKs, `boto3`, the AWS CLI, and presigned URLs all work — reliable and familiar, with no proprietary client.
 
-If the user has no Neon project, isn't on Postgres, and just needs a standalone CDN-backed asset store, a dedicated object store may fit better — but the moment branch-consistent files + rows matter, this is the reason to use it.
+If the files in question ship with the app itself — HTML, JS bundles, CSS, the images in `public/` — that's static web hosting and belongs on Vercel, Netlify, or Cloudflare instead. Public assets that are served from a bucket want a CDN in front of them (see [Architecture: Where Object Storage Fits](#architecture-where-object-storage-fits)).
 
 ## What It Does
 
@@ -55,6 +55,13 @@ If the user has no Neon project, isn't on Postgres, and just needs a standalone
 
 Check this precondition before setting anything up: Neon Object Storage is a public beta feature available in the `us-east-2` region. Confirm the user's Neon project is in `us-east-2` before proceeding.
 
+## Architecture: Where Object Storage Fits
+
+Neon (Object Storage included) is **backend primitives, not full-stack app hosting**. Object Storage holds the files the app and its users produce — uploads, attachments, avatars, documents, generated images, backups — keyed from Postgres rows on the same branch. Two boundaries follow from that:
+
+- **Put a CDN in front of public assets.** A `public_read` object is read anonymously at `${AWS_ENDPOINT_URL_S3}/<bucket>/<object-key>` — the branch's storage endpoint, injected as an env var (see [Environment Variables](#environment-variables)). For assets a browser loads on every page view — avatars, product images, anything hot — use that as the origin for a Cloudflare or Vercel CDN, and set `Cache-Control` on `PutObject` so the edge knows how long to hold each object. A cached object is only as fresh as its key, so write each version to a new key (`avatars/<user-id>/<uuid>.jpg`) and repoint the key stored in Postgres, rather than overwriting one key and waiting out the TTL. The endpoint is branch-scoped, so a production CDN points at the production branch while preview branches read their own endpoint directly rather than sharing a cache. Private buckets stay on presigned URLs instead, which carry their signature in the query string.
+- **Host the app itself elsewhere.** Anything checked into the repo — HTML, JS bundles, CSS, and the images and fonts that ship in `public/` — belongs on Vercel, Netlify, or Cloudflare, along with the index documents, SPA fallbacks, and custom domains that go with them. Neon has no website mode to serve them through: `PutBucketWebsite` returns `501 Not Implemented`.
+
 ## Setup
 
 Object storage is part of the `neon.ts` infrastructure-as-code config (see the `neon` skill for the branch-first workflow, `link`/`checkout`, and `neon.ts` basics). Declare buckets under `preview.buckets`, keyed by bucket name:

package/dist/global-skills/onboarding/SKILL.md

@@ -42,7 +42,11 @@ translate every error · celebrate. Decide all technical choices yourself.
    First run `vybekiit doctor` — it installs the tools the app will need (for the database and for
    putting the app online) so the builder never configures anything. It may say a tool "isn't signed
    in yet" — that's fine for now; sign-in happens later, only when a step needs it (one browser click
-   each). Then install the project's building blocks and start the app yourself, in plain words.
+   each). Then install the project's building blocks. Before starting the app, check whether
+   `http://localhost:3000` already responds and reuse that running preview when it does. Otherwise,
+   start exactly one preview with the agent's background-task support and keep its task handle.
+   If a running preview is unhealthy, inspect and restart that same process instead of starting a
+   second copy. Do this yourself, in plain words.
    After dependencies install, run **quality smoke** yourself: `pnpm verify` (format, lint, typecheck,
    tests). Confirm `.cursorignore` hides `.env` (doctor checks this). Optionally install UI walkthrough
    browsers: `pnpm exec playwright install chromium` (agent-only — see `playwright-vybekiit.md`).

package/dist/global-skills/resend/references/api-keys.md

@@ -85,7 +85,7 @@ keys = resend.ApiKeys.list()
 
 # Rename a key (only "name" is patchable)
 resend.ApiKeys.update({
-    "api_key_id": "api_key_id",
+    "id": "api_key_id",
     "name": "Production Sending Key v2",
 })
 

package/dist/global-skills/resend/references/segments.md

@@ -10,17 +10,17 @@ Group contacts for broadcast targeting. Segments replaced legacy "audiences" —
 |-----------|--------|
 | Create | `resend.segments.create(params)` |
 | Get | `resend.segments.get(id)` |
+| Update | `resend.segments.update(id, { name })` — rename only |
 | List | `resend.segments.list(params?)` |
 | Delete | `resend.segments.remove(id)` — not `.delete()` |
 
-No update endpoint — delete and recreate to rename a segment.
-
 ### Python
 
 | Operation | Method |
 |-----------|--------|
 | Create | `resend.Segments.create(params)` |
 | Get | `resend.Segments.get(id)` |
+| Update | `resend.Segments.update(id, params)` — rename only |
 | List | `resend.Segments.list(params?)` |
 | Delete | `resend.Segments.remove(id)` |
 
@@ -39,6 +39,23 @@ if (error) {
 console.log(data.id); // seg_xxxxxxxx
 ```
 
+## Update Segment
+
+Rename an existing segment. `name` is the only field — the response only returns `object` and `id`, not the new `name`.
+
+```typescript
+const { data, error } = await resend.segments.update('seg_xxx', {
+  name: 'Active Users (Q3)',
+});
+
+if (error) {
+  console.error(error);
+  return;
+}
+
+console.log(data.id); // UUID, e.g. 78261eea-8f8b-4381-83c6-79fa7120f1cf
+```
+
 ## Managing Contacts in Segments
 
 Add or remove contacts from segments via the contacts sub-resource:
@@ -72,6 +89,5 @@ await resend.broadcasts.create({
 | Mistake | Fix |
 |---------|-----|
 | Using `audienceId` | Audiences are deprecated — use `segmentId` |
-| Calling `.update()` | No update endpoint — `.remove()` then `.create()` to rename |
 | Calling `.delete()` | SDK method is `.remove()` |
 | Expecting contacts auto-added | Contacts must be explicitly added via `contacts.segments.add()` |

package/package.json

@@ -1,49 +1,48 @@
 {
   "name": "vybekiit",
-  "version": "0.7.19",
+  "version": "0.7.21",
   "description": "Choose your services, sign in, create a VybeKiit app, and open its verified local welcome page.",
   "license": "MIT",
-  "packageManager": "pnpm@10.33.2",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
   "bin": {
-    "vybekiit": "./dist/bin.js"
+    "vybekiit": "dist/bin.js"
   },
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "tsup && node scripts/bundleGlobalSkills.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@aws-sdk/client-dynamodb": "^3.1075.0",
     "@aws-sdk/client-s3": "^3.1075.0",
     "@aws-sdk/lib-dynamodb": "^3.1075.0",
-    "@clack/prompts": "catalog:",
+    "@clack/prompts": "1.7.0",
     "@neondatabase/serverless": "^0.10.4",
     "@supabase/supabase-js": "^2.47.10",
-    "effect": "catalog:",
+    "effect": "3.21.4",
     "firebase-admin": "^13.0.2",
     "mongodb": "^7.4.0",
-    "open": "catalog:",
+    "open": "11.0.0",
     "playwright": "^1.61.1"
   },
   "devDependencies": {
-    "@types/node": "catalog:",
-    "tsup": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:",
-    "@vybekiit/agent-kit": "workspace:*",
-    "@vybekiit/agent-mcp": "workspace:*",
-    "@vybekiit/core": "workspace:*",
-    "@vybekiit/db": "workspace:*",
-    "@vybekiit/deploy": "workspace:*",
-    "@vybekiit/payments": "workspace:*",
-    "@vybekiit/report-mode": "workspace:*"
+    "@types/node": "22.20.0",
+    "tsup": "8.5.1",
+    "typescript": "5.7.2",
+    "vitest": "3.2.6",
+    "@vybekiit/core": "0.7.21",
+    "@vybekiit/db": "0.7.21",
+    "@vybekiit/agent-mcp": "0.7.21",
+    "@vybekiit/agent-kit": "0.7.21",
+    "@vybekiit/deploy": "0.7.21",
+    "@vybekiit/report-mode": "0.7.21",
+    "@vybekiit/payments": "0.7.21"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/bundleGlobalSkills.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}

package/dist/global-skills/email-best-practices/.github/workflows/sync-skills.yml

@@ -1,30 +0,0 @@
-name: Sync Skills
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - 'SKILL.md'
-      - 'references/**'
-      - 'scripts/**'
-      - 'assets/**'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger sync on resend-skills
-        env:
-          GH_TOKEN: ${{ secrets.SYNC_SKILLS_TO_RESEND_SKILLS }}
-        run: |
-          gh workflow run sync-from-repo.yml \
-            --repo resend/resend-skills \
-            --field repo=email-best-practices \
-            --field skill-path=. \
-            --field skill-name=email-best-practices \
-            --field sha=${{ github.sha }} \
-            --field reviewer=${{ github.actor }}

package/dist/global-skills/email-best-practices/README.md

@@ -1,63 +0,0 @@
-```
-  ╔══════════════════════════════════════╗
-  ║   _____ __  __    _    ___ _         ║
-  ║  | ____|  \/  |  / \  |_ _| |        ║
-  ║  |  _| | |\/| | / _ \  | || |        ║
-  ║  | |___| |  | |/ ___ \ | || |___     ║
-  ║  |_____|_|  |_/_/   \_\___|_____|    ║
-  ║                                      ║
-  ║           Best Practices             ║
-  ╚══════════════════════════════════════╝
-```
-
-# Email Best Practices Skill
-
-A comprehensive agent skill for building production-ready email systems. Covers everything from DNS authentication to webhook processing, with a focus on deliverability, compliance, and reliability.
-
-## Installation
-
-```bash
-npx skills add resend/email-best-practices
-```
-
-## What This Skill Covers
-
-**Getting Started**
-- Planning which emails your app needs (password reset, verification, order confirmations)
-- Setting up email authentication (SPF, DKIM, DMARC) so emails reach inboxes
-
-**Sending Emails**
-- Transactional email design (subject lines, content structure, mobile-first)
-- Marketing email best practices (consent, segmentation, unsubscribe)
-- Compliance requirements by region (CAN-SPAM, GDPR, CASL)
-
-**Production Infrastructure**
-- Idempotency and retry logic to prevent duplicates
-- Webhook processing for delivery events
-- Suppression lists and list hygiene automation
-
-## Structure
-
-```
-email-best-practices/
-├── SKILL.md                             # Start here - routes to the right resource
-└── references/
-    ├── deliverability.md                # SPF/DKIM/DMARC, sender reputation
-    ├── transactional-emails.md          # Password resets, OTPs, confirmations
-    ├── transactional-email-catalog.md   # Email combinations by app type
-    ├── marketing-emails.md              # Newsletters, campaigns, consent
-    ├── email-capture.md                 # Validation, verification, opt-in
-    ├── compliance.md                    # CAN-SPAM, GDPR, CASL
-    ├── email-types.md                   # Transactional vs marketing
-    ├── sending-reliability.md           # Idempotency, retry logic, errors
-    ├── webhooks-events.md               # Delivery events, webhook setup
-    └── list-management.md               # Suppression lists, hygiene
-```
-
-## Quick Start
-
-Open `SKILL.md` - it has a routing table that directs you to the right resource based on what you need to do.
-
-## License
-
-MIT

package/dist/global-skills/email-best-practices/tests/README.md

@@ -1,35 +0,0 @@
-# Skill Tests
-
-Tests for the `email-best-practices` skill using the RED-GREEN methodology from [writing-skills](https://github.com/yourorg/writing-skills).
-
-## Skill Type
-
-This is a **reference/technique** skill (not discipline-enforcing), so tests focus on:
-
-- **Retrieval** — Does the agent find the right resource for a given problem?
-- **Application** — Does the agent produce correct, specific guidance?
-- **Gap** — Are common email scenarios adequately covered?
-
-## Test Scenarios
-
-| # | Scenario | Tests | Key Resource(s) |
-|---|----------|-------|-----------------|
-| 1 | Emails going to spam | Retrieval + Application | deliverability.md |
-| 2 | Multi-region compliance | Retrieval + Application | compliance.md |
-| 3 | Retry logic + idempotency | Application | sending-reliability.md |
-| 4 | Webhook bounce/complaint handling | Application | webhooks-events.md, list-management.md |
-| 5 | New SaaS email infrastructure | Retrieval + Application + Gap | All resources |
-
-## Running Tests
-
-Each scenario in `scenarios/` is a self-contained prompt. Run with a subagent:
-
-**RED (baseline):** Run the prompt as-is — no skill loaded. The agent uses only general knowledge.
-
-**GREEN (with skill):** Prepend: `You have access to an email best practices skill with resources in <path>. Read SKILL.md first, then read the relevant resource file(s).`
-
-Compare outputs against `results.md` for expected correctness criteria.
-
-## Results
-
-See `results.md` for the full RED vs GREEN comparison and gap analysis from the initial test campaign.

package/dist/global-skills/email-best-practices/tests/scenarios/01-spam-deliverability.md

@@ -1,46 +0,0 @@
-# Scenario 1: Emails Going to Spam
-
-## Prompt
-
-```
-You are an AI coding assistant. A developer asks you:
-
-"My transactional emails (password resets, order confirmations) are going to spam in Gmail. What do I do to fix this?"
-
-Answer with specific, actionable steps. Include exact DNS records, commands to verify, and threshold numbers where relevant.
-
-Format your response as a numbered action plan.
-```
-
-## Expected Correctness Criteria
-
-The agent MUST include these skill-specific details:
-
-### Authentication (deliverability.md)
-- [ ] SPF record example: `v=spf1 include:amazonses.com ~all`
-- [ ] DKIM: provider supplies the record
-- [ ] DMARC: `v=DMARC1; p=none; rua=mailto:dmarc@example.com`
-- [ ] DMARC rollout: `p=none` → `p=quarantine; pct=25` → `p=reject`
-- [ ] Verification commands: `dig TXT example.com +short`, `dig TXT resend._domainkey.example.com +short`, `dig TXT _dmarc.example.com +short`
-
-### Thresholds (deliverability.md)
-- [ ] Bounce targets: <1% good, 1-3% acceptable, 3-4% concerning, >4% critical
-- [ ] Complaint targets: <0.01% excellent, 0.01-0.05% good, >0.05% critical
-
-### IP Warming (deliverability.md)
-- [ ] Week 1: 50-100/day
-- [ ] Week 2: 200-500/day
-- [ ] Week 3: 1,000-2,000/day
-- [ ] Week 4: 5,000-10,000/day
-
-### Infrastructure (deliverability.md)
-- [ ] Dedicated subdomains: `t.example.com` (transactional), `m.example.com` (marketing)
-- [ ] DNS TTL: 300s during setup, 3600s+ after stable
-
-### Troubleshooting order (deliverability.md)
-- [ ] Check in order: 1. Authentication, 2. List-Unsubscribe header, 3. Reputation, 4. Content, 5. Sending patterns
-
-### Diagnostic tools (deliverability.md)
-- [ ] Google Postmaster Tools
-- [ ] mail-tester.com
-- [ ] MXToolbox blacklist check

package/dist/global-skills/email-best-practices/tests/scenarios/02-multi-region-compliance.md

@@ -1,48 +0,0 @@
-# Scenario 2: Multi-Region Email Compliance
-
-## Prompt
-
-```
-You are an AI coding assistant. A developer asks you:
-
-"I'm building an email newsletter for my SaaS product. I have users in the US, EU, and Canada. What legal requirements do I need to follow? Give me a comparison table of requirements by region and the specific implementation steps."
-
-Be specific about penalty amounts, timing requirements for unsubscribe processing, and consent record requirements.
-```
-
-## Expected Correctness Criteria
-
-### Penalties (compliance.md)
-- [ ] CAN-SPAM: $53k/email
-- [ ] GDPR: EUR 20M or 4% revenue
-- [ ] CASL: $1M (individual) to $10M (organization) CAD
-
-### Consent types (compliance.md)
-- [ ] CAN-SPAM: opt-out model (can send without opt-in)
-- [ ] GDPR: explicit opt-in (no pre-checked boxes)
-- [ ] CASL express: explicit opt-in
-- [ ] CASL implied: existing relationship (2 years) or inquiry (6 months)
-
-### Unsubscribe timing (compliance.md)
-- [ ] CAN-SPAM: 10 business days, must work 30 days after send
-- [ ] GDPR: immediately, as easy as opting in
-- [ ] CASL: 10 business days, must work 60 days after send
-
-### CASL specifics (compliance.md)
-- [ ] Sender identification valid 60 days after send
-- [ ] Keep consent records 3 years after expiration
-
-### Consent records (compliance.md)
-- [ ] Record: email, date/time, method, what consented to, source
-
-### International sending (compliance.md)
-- [ ] Best practice: follow GDPR (most restrictive) for all regions
-
-### Managing preferences vs unsubscribe (compliance.md)
-- [ ] One-click unsubscribe required; preference management is nice-to-have, doesn't replace unsubscribe
-
-### List-Unsubscribe header (compliance.md)
-- [ ] Required by Gmail/Yahoo since Feb 2024
-- [ ] Headers: `List-Unsubscribe` URL + `List-Unsubscribe-Post: List-Unsubscribe=One-Click`
-- [ ] Endpoint: POST returns 200/202, GET shows unsubscribe page
-- [ ] Stop sending within 48 hours