@sadrmanesh/commerce-agent-skills 0.0.0-stage → 0.3.0

package/rules/checkout-ux-and-conversion.md

@@ -0,0 +1,12 @@
+# Checkout UX and conversion
+
+- Show shipping, tax, discounts, and the charged total before the pay control. Update that total when the address or shipping method changes.
+- Allow guest checkout unless the shop has a written reason not to. Do not force account creation before payment.
+- Validate on the server. Show field errors next to the fields and move focus to the first error.
+- Keep the cart and the typed address when a payment is declined.
+- Make submit idempotent and disable the pay control after the first accepted click.
+- Label the pay control with the action, amount, and currency.
+- Collect card data only in the provider's hosted fields or redirect.
+- Use HTML autocomplete attributes and input types that match the country. Do not force another country's phone or postal-code mask.
+- Confirm with an order number. A reload of the confirmation page must not create or charge an order.
+- Repeat every check in a narrow viewport and with a keyboard. RTL layouts follow the document direction.

package/rules/conversion-event-tracking.md

@@ -0,0 +1,11 @@
+# Conversion event tracking
+
+- Use the event names `view_item`, `add_to_cart`, `begin_checkout`, `add_shipping_info`, `add_payment_info`, `purchase`, and `refund`.
+- Send `items` with a stable `item_id` for the purchasable unit.
+- Set `value` to the sum of item price times quantity. Exclude tax and shipping. Send those as their own purchase fields.
+- Require an ISO currency whenever `value` is set.
+- Fire `purchase` only after payment is confirmed. `transaction_id` is the order number and must be non-empty.
+- Reuse that `transaction_id` on reload and on `refund`. Do not mint a new id per page view.
+- Do not put customer name, email, or phone on the event.
+- Follow the shop's consent settings before loading advertising tags.
+- Run `scripts/check-event.mjs` on the payload. It does not call an analytics service.

package/rules/ecommerce-seo-structured-data.md

@@ -0,0 +1,11 @@
+# Ecommerce SEO structured data
+
+- Emit one Product node that matches the visible product. Do not add a second Product JSON-LD block on a WooCommerce page that already prints one.
+- Prefer the `woocommerce_structured_data_product` filter on WooCommerce. On a custom storefront, render JSON-LD in the server HTML.
+- Use a JSON number for `price` and an ISO 4217 `priceCurrency`. Do not put currency symbols or Persian digits in the price.
+- A variant page marks up that variant's price, SKU, and availability. Do not mark a sold-out unit as `InStock`.
+- Merchant listings need `name`, `image`, and one `Offer` with a price greater than zero. Product snippets can use `AggregateOffer` for a visible price range.
+- If both `offers.price` and `priceSpecification` are set, the offer price is the one Google uses. Keep it positive for a merchant listing.
+- Set `availability` from the unit's stock status. Map WooCommerce `onbackorder` to `BackOrder`.
+- Keep `name` and `description` in the page language. Keep `hreflang` and canonical URLs consistent for translated pages.
+- Run `scripts/check-product-jsonld.mjs` for the `merchant` or `snippet` profile before shipping the markup.

package/rules/fraud-and-risk-basics.md

@@ -0,0 +1,11 @@
+# Fraud and risk basics
+
+- Let the payment provider collect card data. Do not store PAN or CVV. Store the provider payment id and result codes.
+- Treat AVS, CVV, and 3-D Secure results as signals. Do not treat a match as proof or a mismatch as automatic fraud.
+- Do not capture while 3-D Secure is still pending.
+- Put high-amount AVS or CVV mismatches and velocity spikes into a review queue. Do not auto-capture the queue on a timer.
+- Ignore a risk flag supplied by the browser.
+- A payment amount or currency mismatch is not captured.
+- Velocity keys use account, address hash, or provider customer id. They do not use a card number.
+- Review decisions record the reviewer and call the provider idempotently for capture or void.
+- Keep the cart and leave the order unpaid when the provider declines. Do not retry the charge in a loop.

package/rules/google-merchant-product-feeds.md

@@ -0,0 +1,11 @@
+# Google Merchant product feeds
+
+- Emit one item per purchasable unit. Keep `id` stable and at most 50 characters. Share `item_group_id` across variants.
+- Require `id`, `title` or `structured_title`, `description` or `structured_description`, `link`, `image_link`, `availability`, and `price`.
+- Write `price` as major units with a period and an ISO code, such as `15.00 USD`. Availability is `in_stock`, `out_of_stock`, `preorder`, or `backorder`.
+- Send `availability_date` for `preorder` and `backorder`.
+- Match the landing page title, description, price, and availability. Do not put promotional text in the title.
+- Put generated titles and descriptions in the structured attribute with `digital_source_type` `trained_algorithmic_media`.
+- Submit a real GTIN when the product has one. Do not invent digits.
+- Use images of at least 500 by 500 pixels. Merchant Center's stated enforcement date for that minimum is 31 January 2027.
+- Run `scripts/check-feed-item.mjs` before export. It does not call Google.

package/rules/headless-nextjs-storefront.md

@@ -0,0 +1,10 @@
+# Headless Next.js storefront
+
+- Render catalog price and availability in server HTML. Do not require client JavaScript for the price a crawler should see.
+- Keep WooCommerce consumer secrets and Shopify Admin tokens in server environment variables. Do not import them from a client component.
+- Use the public storefront API for carts. WooCommerce carts use the Store API, not `wc/v3`.
+- Store the cart token in an HTTP-only cookie set by a Next.js route. Do not put it in `localStorage` when possession of the token changes the cart.
+- Cache product fetches with a product tag. Do not cache cart responses on a shared public key.
+- Revalidate the product tag from the server when a verified catalog webhook reports a price or stock change.
+- Charge the total returned by the commerce server at checkout, not a total held only in React state.
+- Format visible money for the locale, and keep machine amounts in ASCII on the request you send to payment.

package/rules/inventory-and-multi-warehouse.md

@@ -0,0 +1,10 @@
+# Inventory and multi-warehouse
+
+- Key stock by SKU or variation and location.
+- Keep `on_hand`, `reserved`, and safety stock. Sell only from `available`.
+- Change stock through movement rows with a kind, quantity, and reference. Do not overwrite totals.
+- Reserve with one conditional update or a row lock. Never read and then write in separate steps.
+- Reservations expire. Release them on failed payment or timeout.
+- Allocate to one location when it can fill the whole order. Split across the fewest locations otherwise.
+- Stock in transit is not available at either end of a transfer.
+- Returns go to inspection before they become available again.

package/rules/iranian-payment-gateways.md

@@ -0,0 +1,10 @@
+# Iranian payment gateways
+
+- Create the order unpaid and store the gateway `authority` before redirecting.
+- Find the order on callback by `Authority` from your own record, not by an order id in the query.
+- `Status=NOK` means failed or canceled. Do not call verify.
+- `Status=OK` is not proof. Verify from the server with the same `amount` and `authority`.
+- Verify code `100` marks the order paid once. Code `101` means already verified: no second receipt or stock change.
+- One Toman (IRT) is ten Rial (IRR). Convert in one function and send the unit the gateway expects.
+- Keep `merchant_id` on the server and out of logs.
+- Reconcile unverified payments with a job, so paid shoppers are not refunded by the network.

package/rules/marketplace-search-and-ranking.md

@@ -0,0 +1,10 @@
+# Marketplace search and ranking
+
+- Index each purchasable unit. A variant with its own price or stock is its own document, with parent title and brand copied on.
+- Normalize query text and indexed text the same way: Persian Yeh and Kaf, ASCII digits, ZWNJ removed for matching, bidi marks stripped.
+- Do not stem Persian with an English analyzer, or English with a Persian analyzer.
+- Filter facets by stable value ids. Localize labels. Multi-select inside one facet is OR unless the UI says otherwise. Across facets, combine with AND.
+- An exact SKU or GTIN match outranks a fuzzy title match. In-stock units outrank out-of-stock units when both match.
+- Mark sponsored placements in the UI. Do not fold them into the organic score without a label.
+- Page with a keyset and a stable tiebreaker (`unit_id`), not a deep offset.
+- Reindex from the catalog write path. A deleted variant must leave the index.

package/rules/mcp-store-tooling.md

@@ -0,0 +1,11 @@
+# MCP store tooling
+
+- One tool per job, named `verb_noun`. Never a free-form REST passthrough.
+- Set `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` honestly. They are hints, so enforce scopes on the server too.
+- Every tool has an object `inputSchema` with bounds; structured results use `outputSchema` and `structuredContent`.
+- Report tool failures with `isError: true` and an actionable message.
+- Default to read-only. Require a scope per write area.
+- Refunds, deletes, and bulk changes take `dryRun` and need `confirm: true`.
+- Cap list page sizes and return a way to get the next page.
+- Redact personal data without the customer scope. Keep API keys out of output and logs.
+- Remote servers use Streamable HTTP, check `Origin`, and use OAuth with RFC 9728 metadata.

package/rules/multi-vendor-payouts.md

@@ -0,0 +1,11 @@
+# Multi-vendor payouts
+
+- Put a `vendor_id` on every sellable line. Do not pay a line that has no vendor.
+- Record commission as ledger entries. Do not rewrite the line price to remove the fee.
+- Write payable entries only after the shopper's payment is confirmed. Authorization is not a payout.
+- Hold entries until the stored refund window or delivery rule. Upcoming balance is not the payout sum.
+- Stamp `payout_id` on entries in the same transaction that creates the batch. Retry the provider with the batch idempotency key.
+- A refund adds reversing entries. Do not delete the original sale entries.
+- Keep tax and shipping in their own entries, credited to the party the marketplace named.
+- Sum the ledger at payout time. Do not also sum the original order totals.
+- Record who is merchant of record. Do not assume it is the vendor.

package/rules/order-and-webhook-reliability.md

@@ -0,0 +1,12 @@
+# Order and webhook reliability
+
+- Verify webhook signatures against the raw body with a constant-time compare, before trusting the JSON.
+- Persist the event in a unique inbox, then return 2xx. A delivery attempt id is not an idempotency key.
+- Dedupe WooCommerce webhooks on resource id, topic, and `date_modified_gmt`. `X-WC-Webhook-Delivery-ID` changes every attempt.
+- Fetch the order or payment when the event is out of order or incomplete. Do not apply an older status over a newer one.
+- Compare paid amounts in integer minor units.
+- Make the paid transition idempotent so stock and receipt email run once.
+- Write outbound webhooks from an outbox in the same transaction as the order change.
+- Acknowledge a WooCommerce activation ping with 2xx and do not create an order from it.
+- Return a retryable error only when the event was not stored. WooCommerce disables a webhook after more than five consecutive failures.
+- Serve the handler on the exact delivery URL. WooCommerce does not follow redirects when it posts the body.

package/rules/payment-gateway-integration.md

@@ -0,0 +1,12 @@
+# Payment gateway integration
+
+- Keep card numbers and CVV on the payment provider. Do not post or store them on the merchant server.
+- Create the shop order in an unpaid status before redirecting the shopper.
+- Send a stable idempotency key for each payment attempt, and reuse it when retrying that same attempt.
+- Mark an order paid only from a signed webhook or a server-side retrieve of the provider payment. Ignore success flags on the browser return URL.
+- Compare the paid amount and currency in integer minor units. Reject a mismatch.
+- Make the paid transition idempotent. A second notice for the same provider payment id must not capture, email, or reduce stock again.
+- Map provider states in one place. Unknown states stay unchanged and are logged.
+- Create real refund records through the provider API. Do not only change the order status string.
+- In WooCommerce, confirm capture with `$order->payment_complete( $transaction_id )`. Use `on-hold` when money is not confirmed. Do not write `_transaction_id` with `add_post_meta()`.
+- Register a Checkout block payment method before declaring the gateway ready for block checkout.

package/rules/product-catalog-modeling.md

@@ -0,0 +1,11 @@
+# Product catalog modeling
+
+- Treat each variant as the purchasable unit. A variable parent does not have its own SKU or price.
+- Keep SKUs unique across simple products and variants.
+- Define variation attributes as a closed option list. Each variant sets every variation attribute, and no two variants share a combination.
+- Store prices as decimal strings in major units with an ISO 4217 currency. Do not persist binary floats.
+- Put stock on the purchasable unit. Managed stock has a quantity. Unmanaged stock has a status and a null quantity.
+- Do not maintain a second parent quantity that can disagree with its variants.
+- Keep attribute option codes stable and translate only the display label.
+- Validate the catalog document with `scripts/validate-catalog.mjs` before importing it.
+- After writing WooCommerce variations, call `WC_Product_Variable::sync()` so the parent price range and stock status match the children.

package/rules/product-description-guardrails.md

@@ -0,0 +1,10 @@
+# Product description guardrails
+
+- Generate copy only from the source record: name, price, currency, locale, and listed facts.
+- Omit a material, dimension, origin, or certification that is not in the facts. Do not substitute a typical value.
+- State the price only as the source amount and ISO currency, or leave the price out.
+- Refuse cure, clinically proven, guaranteed to, 100% effective, and risk-free claims unless that phrase is in `allowedClaims`.
+- Write the description in the requested locale. Do not add facts while translating.
+- Label generated Merchant Center text with `digital_source_type` `trained_algorithmic_media`.
+- Keep titles within 150 characters and descriptions within 5000.
+- Run `scripts/check-description.mjs`. A pass does not prove the description is accurate.

package/rules/returns-and-refunds.md

@@ -0,0 +1,10 @@
+# Returns and refunds
+
+- Keep each return as its own record (RMA) linked to the order, with lines, reason, and state.
+- Check the return window, returnable flags, and already returned quantities on the server.
+- Refund from the inspection result, not from the request.
+- Restock only resellable units, as a `return` stock movement. Quarantine damaged units.
+- Refund through the original payment method with an idempotency key. Store the provider refund id.
+- Never refund more than was captured. Check earlier refunds inside the transaction.
+- Refund tax in proportion. Refund shipping only when the policy says so.
+- A partial refund keeps the order paid for the rest.

package/rules/rtl-and-persian-localization.md

@@ -0,0 +1,11 @@
+# RTL and Persian localization
+
+- Set Persian pages to `lang="fa"` and `dir="rtl"`. In WordPress, rely on the `fa_IR` locale and `is_rtl()`.
+- Use CSS logical properties (`margin-inline-start`, `text-align: start`). Do not fix layout by rewriting `left` and `right` in a copied stylesheet.
+- Mirror back and forward icons. Do not mirror logos, payment marks, product photos, or numbers.
+- Fold Arabic Yeh and Kaf to Persian Yeh and Kaf on input. Keep ZWNJ in stored and displayed text. Remove ZWNJ only in search tokens.
+- Keep ASCII digits in APIs, SKUs, JSON, and payment amounts. Persian digits are a display format. Accept Arabic-Indic digits on input.
+- Store WooCommerce order dates as Gregorian timestamps. A Jalali calendar is display-only.
+- Use ISO `IRR` for rials. If the shop charges in toman, store one unit and label it. Do not divide by 10 only in the theme.
+- Format prices with `wc_price()`. Translate strings with gettext placeholders, not concatenation.
+- Load a font that covers Arabic script. Do not run digit conversion across an entire HTML document.

package/rules/shopify-app-development.md

@@ -0,0 +1,10 @@
+# Shopify app development
+
+- Configure the API version and app-specific webhooks in `shopify.app.toml`. Do not hard-code an API version in a handler.
+- Authenticate before trusting a shop domain. Embedded admin requests need a validated session token. App proxy signatures do not authorize shop changes.
+- Use the GraphQL Admin API for new admin work, with the narrowest scope that mutation needs.
+- Verify HTTPS webhooks with HMAC-SHA256 of the raw body and the app client secret. The header is `X-Shopify-Hmac-Sha256`. Compare header names case-insensitively.
+- Dedupe webhook retries with `X-Shopify-Webhook-Id`. Do not trust topic or shop headers before the HMAC matches.
+- Read GraphQL `userErrors` even when the HTTP status is 200.
+- Keep the previous client secret only for the rotation window Shopify documents, up to an hour, and do not log tokens or secrets.
+- Reject shop domains that are not anchored to one `myshopify.com` host.

package/rules/storefront-accessibility.md

@@ -0,0 +1,11 @@
+# Storefront accessibility
+
+- Target WCAG 2.2 AA from search to order confirmation.
+- Use native `<button>`, `<a href>`, `<select>`, radio groups, and `<fieldset>` with `<legend>`.
+- Every field has a visible `<label>` and an `autocomplete` token. Placeholders are not labels.
+- Keep a visible focus style that sticky headers do not cover.
+- Announce cart updates and result counts in a `role="status"` live region.
+- Errors are text that names the field, with `aria-invalid` and focus moved to the summary.
+- Contrast: 4.5:1 text, 3:1 large text and UI parts. Targets at least 24 by 24 CSS pixels.
+- Drawers and modals move focus in and return it on close.
+- Allow paste and password managers. Do not ask for the same data twice.

package/rules/storefront-performance.md

@@ -0,0 +1,10 @@
+# Storefront performance
+
+- Judge Core Web Vitals on field data at the 75th percentile, mobile and desktop apart.
+- Good means LCP at most 2500 ms, INP at most 200 ms, CLS at most 0.1.
+- Never lazy-load the main product image. Give it `fetchpriority="high"` and the right size.
+- Set image dimensions and reserve space for banners and widgets.
+- Break up long tasks and defer third-party scripts.
+- Cache catalog pages for anonymous shoppers only. Bypass cart, checkout, account, and session cookies.
+- Purge cached pages when price or stock changes.
+- Recheck field data over 28 days after a change.

package/rules/stripe-payments.md

@@ -0,0 +1,10 @@
+# Stripe payments
+
+- Create the PaymentIntent or Checkout Session on the server from the order total, with `metadata[order_id]` and an `Idempotency-Key` per attempt.
+- Send amounts as integers in the currency's smallest unit. Respect zero-decimal currencies.
+- Only the `client_secret` or Checkout `url` reaches the browser. The `sk_` key stays on the server.
+- Mark orders paid from a verified webhook: `payment_intent.succeeded`, or `checkout.session.completed` with `payment_status` `paid`.
+- Verify `Stripe-Signature` on the raw body with the `whsec_` secret, a 300 second tolerance, and a constant-time compare.
+- Deduplicate on `event.id`. Compare `amount_received` and `currency` with the order.
+- Refund with `POST /v1/refunds` and an idempotency key. Track pending refunds from `refund.updated`.
+- Never treat the `return_url` visit as proof of payment.

package/rules/subscription-billing.md

@@ -0,0 +1,10 @@
+# Subscription billing
+
+- Store the subscription separately from invoices: status, interval, and period start and end in UTC.
+- Activate a paid plan only after the first charge is confirmed. A trial stores its end and does not pretend a charge succeeded.
+- Create one renewal invoice per period. Retry that charge with the same idempotency key. Do not advance the period until the charge succeeds.
+- Map provider statuses in one function. Unknown statuses do not move the contract.
+- Cancel at period end is different from canceling now. Record which one the shopper chose.
+- Prorate plan changes on their own invoice lines. Do not edit a paid invoice in place.
+- On the first failed renewal, follow the dunning schedule. Do not delete the entitlement immediately unless the plan says so.
+- Do not implement WooCommerce renewals with `wp_insert_post`. Use the subscription product the store already runs.

package/rules/tax-and-shipping.md

@@ -0,0 +1,10 @@
+# Tax and shipping
+
+- Take tax rates from the store's configuration or its tax service. Do not invent a percent in the theme or the client.
+- Store each tax line with its rate id and amount. Do not recompute a historical order from today's rate table.
+- Respect inclusive versus exclusive catalog prices. Do not mix them on one order.
+- Match shipping zones from the destination. A missing zone is not a free rate. A configured zero cost is a free method.
+- Recalculate tax and shipping on the server when the address or the cart changes, and show both before payment.
+- Persist the chosen shipping method id and the quoted amount on the order.
+- In WooCommerce, use `WC_Tax` and `WC_Shipping_Method`. Do not write a second rate table in JavaScript.
+- Refund tax from the tax that was stored on the refunded lines.

package/rules/vector-product-search.md

@@ -0,0 +1,10 @@
+# Vector product search
+
+- Embed one vector per purchasable unit, not one vector per parent when variants differ.
+- Use the same model, dimension, and similarity metric for the index and the query. Store `model_id` and a hash of the embedded text.
+- Normalize text the same way as lexical search before embedding, including Persian folds.
+- Keep SKU and GTIN lookup ahead of vector ranking. An exact identifier match wins.
+- Filter facets and stock in the vector query. Do not rely on the embedding to enforce them.
+- Leave price and stock out of the embedded text so a price change does not force a new vector.
+- Re-embed when the text hash or the model id changes. Delete vectors for deleted units.
+- Write down the lexical and vector weights. Do not treat a default weight as a measured result.

package/rules/woocommerce-plugin-development.md

@@ -0,0 +1,10 @@
+# WooCommerce plugin development
+
+- Read and write orders and products with WooCommerce CRUD (`wc_get_order`, `wc_get_product`, setters, one `save()`). Do not use `get_post`, `get_post_meta`, `update_post_meta`, or `get_posts` for orders.
+- Declare HPOS compatibility from the main plugin file on `before_woocommerce_init` via `FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true )` only after every order path is CRUD-based. Include a `WC tested up to` header.
+- Hook both classic checkout and the Store API checkout. `woocommerce_checkout_create_order` does not run for the Checkout block.
+- Register order admin UI on `wc_get_page_screen_id( 'shop-order' )`. Do not rely on `save_post_shop_order`.
+- Authorize writes with a capability (`edit_shop_orders`, `edit_products`, `manage_woocommerce`) and a nonce. A nonce is not authentication.
+- Create refunds with `wc_create_refund()`. Do not only set the order status to `refunded`.
+- Leave stock reduction to WooCommerce payment and status transitions. Do not decrement quantity again in your hook.
+- Wrap user-facing strings in gettext calls with the plugin text domain. Load a privately distributed text domain on `init`.

package/rules/woocommerce-rest-api.md

@@ -0,0 +1,10 @@
+# WooCommerce REST API
+
+- Call `/wp-json/wc/v3/` from the server. Do not send consumer secrets to the browser or to the Store API (`/wp-json/wc/store/v1/`).
+- Authenticate over HTTPS with HTTP Basic auth: consumer key as the username, consumer secret as the password. Use query-string credentials only when the host strips `Authorization`, and never over plain HTTP.
+- Bind each key to a user and a Read, Write, or Read/Write permission that matches the job. A deleted user disables the key.
+- Page with `per_page` at most 100 and stop on `X-WP-TotalPages`. Compare times with the `*_gmt` fields.
+- Treat creates as unsafe to retry. Store your own idempotency key in meta and look it up before posting again.
+- Read every item in a batch response. A batch is not one transaction.
+- Register webhooks with an explicit secret. Acknowledge the activation ping with 2xx and do not create an order from it.
+- Verify `X-WC-Webhook-Signature` on the raw body. Do not dedupe solely on `X-WC-Webhook-Delivery-ID`.

package/rules/wordpress-plugin-security.md

@@ -0,0 +1,10 @@
+# WordPress plugin security
+
+- Check a capability with `current_user_can()`, not a role name. Use `edit_shop_orders`, `edit_products`, or `manage_woocommerce` for shop operations.
+- Verify a nonce on cookie-authenticated state changes. A nonce does not authenticate the user and does not belong on a server-to-server webhook.
+- Unslash request data, sanitize it to a known type, and escape on output for the HTML, attribute, or URL context you are writing.
+- Pass SQL values through `$wpdb->prepare()`. Never build a table name or filesystem path from request input.
+- Give every private REST route a `permission_callback` that checks a capability. Do not use `__return_true` for order, customer, or payment data.
+- Authorize the specific object after you load it. A posted order id is not proof that this user may edit that order.
+- Store structured meta as JSON or scalars. Do not `unserialize()` request data.
+- Keep secrets, card data, and full `$_POST` payloads out of logs and order notes.

package/scripts/lib/frontmatter.mjs

@@ -0,0 +1,218 @@
+/**
+ * Parse the YAML subset used by SKILL.md frontmatter in this repository.
+ * Supports top-level scalars, one-level nested maps, and folded/literal blocks.
+ */
+
+const TOP_LEVEL_KEYS = new Set([
+  "name",
+  "description",
+  "license",
+  "compatibility",
+  "metadata",
+  "allowed-tools",
+]);
+
+export function splitFrontmatter(text) {
+  const normalized = text.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    throw new Error("SKILL.md must start with a --- frontmatter delimiter");
+  }
+  const end = normalized.indexOf("\n---\n", 4);
+  if (end === -1) {
+    throw new Error("SKILL.md is missing the closing --- frontmatter delimiter");
+  }
+  return {
+    yaml: normalized.slice(4, end),
+    body: normalized.slice(end + "\n---\n".length),
+    normalized,
+  };
+}
+
+export function parseFrontmatter(yaml) {
+  const lines = yaml.split("\n");
+  const root = {};
+  const seen = new Set();
+  let index = 0;
+
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line.trim() === "" || /^\s*#/.test(line)) {
+      index += 1;
+      continue;
+    }
+    if (/^\s/.test(line)) {
+      throw new Error(`Unexpected indented line outside a block: ${line}`);
+    }
+    const match = line.match(/^([A-Za-z0-9][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!match) {
+      throw new Error(`Invalid frontmatter line: ${line}`);
+    }
+    const key = match[1];
+    const raw = match[2];
+    if (seen.has(key)) {
+      throw new Error(`Duplicate frontmatter field: ${key}`);
+    }
+    seen.add(key);
+
+    if (raw === "" || raw === "|" || raw === ">" || raw === "|-" || raw === ">-") {
+      const block = [];
+      index += 1;
+      while (index < lines.length && (lines[index].startsWith("  ") || lines[index].trim() === "")) {
+        block.push(lines[index]);
+        index += 1;
+      }
+      root[key] = raw === "" ? parseNestedMap(block, key) : parseBlockScalar(raw, block);
+      continue;
+    }
+
+    root[key] = parseScalar(raw, key);
+    index += 1;
+  }
+
+  return root;
+}
+
+function parseNestedMap(blockLines, parentKey) {
+  const value = {};
+  const seen = new Set();
+  for (const line of blockLines) {
+    if (line.trim() === "" || /^\s*#/.test(line)) {
+      continue;
+    }
+    const match = line.match(/^  ([A-Za-z0-9][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!match) {
+      throw new Error(`Invalid ${parentKey} entry: ${line}`);
+    }
+    if (match[2] === "") {
+      throw new Error(`Nested blocks under ${parentKey}.${match[1]} are not supported`);
+    }
+    if (seen.has(match[1])) {
+      throw new Error(`Duplicate ${parentKey} field: ${match[1]}`);
+    }
+    seen.add(match[1]);
+    value[match[1]] = parseScalar(match[2], `${parentKey}.${match[1]}`);
+  }
+  return value;
+}
+
+function parseBlockScalar(style, blockLines) {
+  const content = blockLines.map((line) => (line.startsWith("  ") ? line.slice(2) : line.trim() === "" ? "" : line));
+  while (content.length > 0 && content[content.length - 1] === "") {
+    content.pop();
+  }
+  const text = content.join("\n");
+  if (style.startsWith(">")) {
+    return text
+      .split(/\n{2,}/)
+      .map((paragraph) => paragraph.replace(/\n/g, " ").trim())
+      .join("\n\n")
+      .trim();
+  }
+  return text;
+}
+
+function parseScalar(raw, keyPath) {
+  const value = raw.trim();
+  if (value.startsWith('"')) {
+    if (!value.endsWith('"') || value.length < 2) {
+      throw new Error(`Unclosed double quote in ${keyPath}`);
+    }
+    return decodeDoubleQuoted(value.slice(1, -1), keyPath);
+  }
+  if (value.startsWith("'")) {
+    if (!value.endsWith("'") || value.length < 2) {
+      throw new Error(`Unclosed single quote in ${keyPath}`);
+    }
+    return value.slice(1, -1).replaceAll("''", "'");
+  }
+  if (value === "" || value === "~" || value === "null" || value === "Null" || value === "NULL") {
+    throw new Error(`${keyPath} must be a non-empty string`);
+  }
+  if (/^(true|false|True|False|TRUE|FALSE)$/.test(value) || /^-?\d/.test(value)) {
+    throw new Error(
+      `${keyPath} must be a quoted string so YAML parsers keep it a string (got ${value})`,
+    );
+  }
+  if (value.includes(": ") || value.startsWith("{") || value.startsWith("[") || value.includes(" #")) {
+    throw new Error(`${keyPath} contains YAML syntax; wrap it in double quotes`);
+  }
+  return value;
+}
+
+function decodeDoubleQuoted(text, keyPath) {
+  let out = "";
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] !== "\\") {
+      out += text[i];
+      continue;
+    }
+    const next = text[i + 1];
+    if (next === undefined) {
+      throw new Error(`Trailing escape in ${keyPath}`);
+    }
+    const map = { n: "\n", t: "\t", '"': '"', "\\": "\\" };
+    if (!(next in map)) {
+      throw new Error(`Unsupported escape \\${next} in ${keyPath}`);
+    }
+    out += map[next];
+    i += 1;
+  }
+  return out;
+}
+
+export function assertSpecFrontmatter(data) {
+  const errors = [];
+  for (const key of Object.keys(data)) {
+    if (!TOP_LEVEL_KEYS.has(key)) {
+      errors.push(`Unknown frontmatter field "${key}". Use name, description, license, compatibility, metadata, or allowed-tools.`);
+    }
+  }
+
+  const name = data.name;
+  if (typeof name !== "string") {
+    errors.push("name is required");
+  } else if (name.length < 1 || name.length > 64) {
+    errors.push(`name must be 1-64 characters (got ${name.length})`);
+  } else if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    errors.push(
+      "name must be lowercase letters, numbers, and single hyphens, and must not start or end with a hyphen",
+    );
+  }
+
+  const description = data.description;
+  if (typeof description !== "string" || description.trim() === "") {
+    errors.push("description is required");
+  } else if (description.length > 1024) {
+    errors.push(`description must be at most 1024 characters (got ${description.length})`);
+  }
+
+  if (data.license !== undefined && (typeof data.license !== "string" || data.license.trim() === "")) {
+    errors.push("license must be a non-empty string when set");
+  }
+
+  if (data.compatibility !== undefined) {
+    if (typeof data.compatibility !== "string" || data.compatibility.trim() === "") {
+      errors.push("compatibility must be a non-empty string when set");
+    } else if (data.compatibility.length > 500) {
+      errors.push(`compatibility must be at most 500 characters (got ${data.compatibility.length})`);
+    }
+  }
+
+  if (data.metadata !== undefined) {
+    if (data.metadata === null || typeof data.metadata !== "object" || Array.isArray(data.metadata)) {
+      errors.push("metadata must be a map of strings");
+    } else {
+      for (const [key, value] of Object.entries(data.metadata)) {
+        if (typeof value !== "string" || value.trim() === "") {
+          errors.push(`metadata.${key} must be a non-empty string`);
+        }
+      }
+    }
+  }
+
+  if (data["allowed-tools"] !== undefined && typeof data["allowed-tools"] !== "string") {
+    errors.push("allowed-tools must be a space-separated string when set");
+  }
+
+  return errors;
+}

package/skills/b2b-pricing/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: b2b-pricing
+description: "Price for business buyers with customer-group price lists, quantity tiers, contract prices, minimum quantities, net terms, and tax exemption, resolved on the server. Use when adding wholesale or B2B prices, tiered pricing, quotes, or company accounts to a store."
+license: MIT
+compatibility: "The price resolver needs Node.js 20 or newer and no packages."
+metadata:
+  author: Naser Sadrmanesh
+  version: "0.3.0"
+---
+
+# B2B pricing
+
+Business buyers see different prices for the same SKU. The price must be resolved by one server function from the buyer's account, the quantity, and the date, and the same function must run in the catalog, the cart, and the order. Data shapes are in [the price list notes](references/price-lists.md).
+
+## Procedure
+
+1. Attach buyers to a company account, and the company to one or more customer groups. A person can buy for more than one company; the cart belongs to one.
+2. Store prices as price lists: a list has a currency, a validity window, a priority, and entries of SKU, minimum quantity, and unit price or a percentage off the base price.
+3. Resolve the unit price in one function: contract price for this company, then group price lists by priority, then the public price. Within a list, use the highest tier whose minimum quantity the line meets.
+4. Show the buyer the next tier ("10 or more: 8.50 each") so they can choose the quantity.
+5. Enforce minimum order quantities and pack sizes (order multiples) in the cart, with a message, not only at checkout.
+6. Recalculate prices on every cart change and again when the order is placed. The price stored on the order line is final.
+
+## Resolution
+
+Run `node scripts/resolve-price.mjs request.json lists.json` to see which list and tier win for a line. It returns the unit price, the source, and the next tier.
+
+Decide and write down what happens when two rules apply. The usual answer is the contract price wins if one exists. Otherwise the lowest price from the active lists wins. Some stores use priority instead. Pick one; mixing them gives prices nobody can explain.
+
+## Terms, quotes, and tax
+
+- Net terms (Net 30) are a payment method that creates an unpaid invoice with a due date. Check the company's credit limit against open invoices before allowing it.
+- A quote is a price offer with an expiry, created by staff or requested by the buyer. Accepting it creates a cart with the quoted prices locked until the expiry.
+- Tax-exempt buyers need a stored exemption certificate or a validated tax id. In the EU, a cross-border B2B sale to a buyer with a valid VAT number (checked through VIES) can use the reverse charge. Store the check result on the order.
+- Show prices with or without tax according to what the buyer's group expects, and say which one is shown.
+
+## Gotchas
+
+- Computing the B2B price in the browser lets anyone see or send another group's price. Resolve on the server and render the result.
+- Caching a product page that shows a group price serves that price to every visitor. Vary the cache by group, or load the price separately.
+- A tier is per line by default. If the store promises mix-and-match tiers across a product's variations, sum the quantity across those lines first.
+- Percent-off entries on a list need a defined base: the public regular price, not the sale price, unless the store says otherwise.
+- Changing a price list must not change orders already placed.
+
+## Verification
+
+- A guest sees the public price. A buyer in the wholesale group sees the wholesale price on the product page, in the cart, and on the order.
+- With the example list in the notes, 9 units cost 9.00 each (the 1+ tier) and 10 units cost 8.50 each (the 10+ tier).
+- A company with a contract price gets it even when a group list is lower, if the store's rule says contract wins.
+- An order below the minimum quantity cannot be placed.
+- Net terms are refused when open invoices plus the order exceed the credit limit.
+
+## Evaluation
+
+Worked examples and the checks they must satisfy are in [evals/tasks.json](evals/tasks.json).

package/skills/b2b-pricing/evals/examples/net-terms.md

@@ -0,0 +1,3 @@
+Net 30 is offered only to companies with terms enabled. Before accepting the order, sum the company's open invoices and add this order total. If that exceeds the credit limit, refuse invoice payment and offer card payment instead.
+
+If it fits, place the order as unpaid, create an invoice with a due date 30 days after the invoice date, and send it to the company's billing contact. Overdue invoices block further orders on terms.

package/skills/b2b-pricing/evals/examples/tiered-wholesale.md

@@ -0,0 +1,3 @@
+The unit price is resolved on the server by one function used by the product page, the cart, and order placement. The wholesale group has a price list with two entries for the mug: `minQuantity` 1 at 9.00 and `minQuantity` 10 at 8.50.
+
+A wholesale buyer ordering 9 mugs gets 9.00 each and sees "10 or more: 8.50 each". At 10 mugs the line is priced at 8.50 each. A guest matches no list and pays the public 11.00. The product page cache varies by group so the wholesale price is never shown to guests.