@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/e2e-testing-playwright/references/config-and-ci.md

@@ -0,0 +1,129 @@
+# Playwright config and CI
+
+Read this when creating or reworking `playwright.config.ts` or the CI job. Check option names against playwright.dev/docs/test-configuration for the installed version.
+
+## Starting config
+
+```ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: process.env.CI ? [['html', { open: 'never' }], ['github']] : 'html',
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' },
+      dependencies: ['setup'],
+    },
+  ],
+  webServer: {
+    command: 'npm run start',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+Add Firefox, WebKit or mobile projects (`devices['Pixel 7']`, `devices['iPhone 15']`) only when the product supports them; each project multiplies run time.
+
+## Auth setup file
+
+```ts
+// e2e/auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.E2E_USER!);
+  await page.getByLabel('Password').fill(process.env.E2E_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page.getByRole('button', { name: 'Account' })).toBeVisible();
+  await page.context().storageState({ path: authFile });
+});
+```
+
+## Custom fixture
+
+```ts
+// e2e/fixtures.ts
+import { test as base } from '@playwright/test';
+
+type Fixtures = { project: { id: string; name: string } };
+
+export const test = base.extend<Fixtures>({
+  project: async ({ request }, use, testInfo) => {
+    const name = `e2e-${testInfo.testId}`;
+    const res = await request.post('/api/projects', { data: { name } });
+    const project = await res.json();
+    await use(project);
+    await request.delete(`/api/projects/${project.id}`);
+  },
+});
+export { expect } from '@playwright/test';
+```
+
+## GitHub Actions with sharding
+
+```yaml
+name: e2e
+on: [push, pull_request]
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1/4, 2/4, 3/4, 4/4]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test --shard=${{ matrix.shard }}
+        env:
+          E2E_USER: ${{ secrets.E2E_USER }}
+          E2E_PASSWORD: ${{ secrets.E2E_PASSWORD }}
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with:
+          name: playwright-report-${{ strategy.job-index }}
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 14
+```
+
+To combine shard reports into one, use the `blob` reporter on CI and `npx playwright merge-reports --reporter html ./all-blob-reports` in a follow-up job.
+
+## Useful commands
+
+| Goal | Command |
+|---|---|
+| Run one file | `npx playwright test e2e/checkout.spec.ts` |
+| Run by title | `npx playwright test -g "applies coupon"` |
+| Debug step by step | `npx playwright test --debug` |
+| Interactive runner | `npx playwright test --ui` |
+| Re-run last failures | `npx playwright test --last-failed` |
+| Stress a test | `npx playwright test e2e/x.spec.ts --repeat-each=20` |
+| Open a trace | `npx playwright show-trace test-results/.../trace.zip` |
+| Open the report | `npx playwright show-report` |
+| Record a draft test | `npx playwright codegen http://localhost:3000` |
+
+Treat `codegen` output as a draft: replace its locators with role-based ones and add assertions.

package/skills/ef-core-patterns/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ef-core-patterns
+description: Entity Framework Core data-access rules for .NET - scoped DbContext lifetime, pooling and IDbContextFactory, AsNoTracking for read paths, LINQ that translates to SQL instead of throwing or evaluating on the client, projections, Include versus AsSplitQuery for N+1 and cartesian explosion, ExecuteUpdate and ExecuteDelete for bulk writes, safe dotnet ef migrations and idempotent scripts, and optimistic concurrency with row versions. Use when writing or reviewing EF Core queries or DbContext setup, fixing slow or untranslatable LINQ, adding or deploying an EF Core migration, or handling DbUpdateConcurrencyException.
+license: MIT
+compatibility: Any Agent Skills host. Needs the .NET SDK and the dotnet-ef tool for migrations. Written for EF Core 8 and later.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "dotnet"
+  kete-loom/owner: "Kete-org"
+---
+
+# EF Core patterns
+
+Use EF Core so every query is one you would have written by hand, and every write is safe under concurrency. For the web host around it follow `aspnet-core-patterns`; for engine-specific SQL tuning follow `postgres-patterns` or `mysql-patterns`.
+
+## 0. Before you change anything
+
+1. Read the `Microsoft.EntityFrameworkCore.*` package versions and the provider (SqlServer, Npgsql, Sqlite, Pomelo MySQL). Behaviour differs by provider.
+2. Turn on SQL logging locally so you can see what each query does:
+   ```csharp
+   options.UseNpgsql(cs).LogTo(Console.WriteLine, LogLevel.Information)
+          .EnableSensitiveDataLogging(env.IsDevelopment());
+   ```
+3. Run `dotnet test`. If it fails before you start, **stop and tell the user**.
+
+## 1. DbContext lifetime
+
+- Web apps: `AddDbContext<AppDbContext>` registers it **scoped**, one per request. For hot paths, `AddDbContextPool<AppDbContext>` reuses instances; pooled contexts must not hold per-request state in fields.
+- Singletons, background services, Blazor Server components and parallel work: inject `IDbContextFactory<AppDbContext>` (`AddDbContextFactory`) and `await using var db = await factory.CreateDbContextAsync(ct);`.
+- A `DbContext` is not thread-safe. Never run two queries on the same context at once (`Task.WhenAll` over one context throws). Use separate contexts.
+- Keep a context short-lived. A long-lived context's change tracker grows and serves stale data.
+
+## 2. Tracking vs no-tracking
+
+| Path | Use |
+|---|---|
+| Read-only list or detail | `AsNoTracking()` or a `Select` projection |
+| Read then update the same entities | Tracking (default), then `SaveChangesAsync` |
+| Read-only with repeated references you need deduplicated | `AsNoTrackingWithIdentityResolution()` |
+
+- Set `UseQueryTrackingBehavior(QueryTrackingBehavior.NoTracking)` on the context only if the whole codebase is read-heavy and every update path re-attaches explicitly. Otherwise opt in per query.
+- Projections (`Select(o => new OrderDto(...))`) are never tracked and fetch only the columns used. Prefer them for APIs.
+
+## 3. Query translation pitfalls
+
+1. Keep the query `IQueryable` until the end. `ToList()`, `AsEnumerable()` or `IEnumerable<T>` parameters in the middle pull every row into memory and filter in C#.
+2. Methods EF can't translate (your own C# helpers, most string formatting, complex `GroupBy` shapes) throw `InvalidOperationException: ... could not be translated`. Rewrite with translatable operators, move the logic to after a projection that already limits rows, or use `FromSql` with parameters.
+3. Client evaluation is allowed only in the final `Select`. Don't rely on it for filtering.
+4. `string.Equals(a, b, StringComparison.OrdinalIgnoreCase)` usually doesn't translate; use the column's collation, `EF.Functions.ILike` (Npgsql) or `EF.Functions.Like`.
+5. `Contains` over a local list becomes `IN` or a parameterised array; keep lists bounded.
+6. Raw SQL: `FromSql($"... WHERE id = {id}")` and `ExecuteSql($"...")` parameterise interpolated values. `FromSqlRaw` / `ExecuteSqlRaw` with string concatenation is SQL injection.
+7. Always `await` the async operators (`ToListAsync`, `FirstOrDefaultAsync`, `SaveChangesAsync`) and pass the `CancellationToken`.
+8. Paginate with `OrderBy` then `Skip`/`Take` (or keyset `Where(x => x.Id > lastId)` for deep pages). `Skip` without `OrderBy` gives unstable pages.
+
+## 4. N+1, Include and split queries
+
+- Lazy loading proxies make N+1s invisible. If the project has `UseLazyLoadingProxies()`, don't add more reliance on it; load explicitly.
+- Load what you need: `Include(o => o.Lines).ThenInclude(l => l.Product)`, or better, a projection that selects just the fields.
+- Several collection `Include`s in one query cause cartesian explosion (rows multiply). EF warns about this. Use `AsSplitQuery()` on that query, or `UseQuerySplittingBehavior(QuerySplittingBehavior.SplitQuery)` globally with `AsSingleQuery()` where you need one round trip.
+- Split queries are not one snapshot: data can change between them. Use a transaction with a suitable isolation level when consistency matters, and always `OrderBy` before `Skip`/`Take` with split queries.
+- Filtered include: `Include(o => o.Lines.Where(l => !l.Cancelled))`.
+
+## 5. Writes
+
+- Bulk changes without loading: `ExecuteUpdateAsync(s => s.SetProperty(o => o.Status, OrderStatus.Archived), ct)` and `ExecuteDeleteAsync(ct)`. They bypass the change tracker, interceptors that hook `SaveChanges`, and concurrency checks. Say so when you use them.
+- One `SaveChangesAsync` per unit of work; it runs in a transaction. Use `await using var tx = await db.Database.BeginTransactionAsync(ct);` only when you span several `SaveChanges` or raw SQL.
+- With retrying execution strategies (`EnableRetryOnFailure`), wrap manual transactions in `db.Database.CreateExecutionStrategy().ExecuteAsync(...)`.
+
+## 6. Concurrency tokens
+
+```csharp
+// SQL Server rowversion
+[Timestamp] public byte[] RowVersion { get; set; } = [];
+// Any provider: an app-managed token
+modelBuilder.Entity<Account>().Property(a => a.Version).IsConcurrencyToken();
+// Npgsql: a uint property marked as row version maps to the xmin system column
+public uint Version { get; set; }
+modelBuilder.Entity<Account>().Property(a => a.Version).IsRowVersion();
+```
+
+- Handle `DbUpdateConcurrencyException`: reload the entry (`entry.GetDatabaseValuesAsync()`), then retry, merge or return 409 to the client. Never catch and ignore it.
+- APIs send the token to the client (ETag or a field) and require it on update, so stale writes are rejected.
+- An app-managed token must be changed on every update (for example `Version = Guid.NewGuid()` or an incremented int).
+
+## 7. Migrations
+
+1. Create: `dotnet ef migrations add AddInvoiceTable` (add `--project` / `--startup-project` when the context lives in another project).
+2. **Read the generated migration.** EF can scaffold a rename as drop plus add; edit it to `RenameColumn` when that happens. Check for data loss before you commit it.
+3. Never edit a migration that has been applied in a shared environment; add a new one.
+4. Deploy with an idempotent script or a bundle, reviewed and run by the pipeline:
+   ```
+   dotnet ef migrations script --idempotent -o migrate.sql
+   dotnet ef migrations bundle --self-contained
+   ```
+   Prefer this over `Database.Migrate()` at app startup in production: startup migration needs schema rights for the app identity and gives no review step. Before EF Core 9, several instances migrating at once could also race; EF Core 9+ takes a database-wide lock but SQL scripts do not.
+   Add `dotnet ef migrations has-pending-model-changes` to CI (EF Core 8+) so a model change without a migration fails the build.
+5. Large tables: add nullable columns, backfill in batches, then make them required in a later migration. Raw SQL for things EF can't express (`migrationBuilder.Sql(...)`, for example concurrent index creation on PostgreSQL with the transaction suppressed).
+6. Keep the model snapshot in source control and resolve merge conflicts in it by re-adding the migration, not by hand-merging.
+
+## Stop and ask the user
+
+- Before a migration that drops or renames a column or table with data.
+- Before turning on global no-tracking, global split queries or lazy loading.
+- Before running migrations against any non-local database.
+
+## Never
+
+- Never register `DbContext` as a singleton or share one across threads.
+- Never build SQL with string concatenation in `FromSqlRaw` / `ExecuteSqlRaw`.
+- Never `ToList()` a table to filter it in memory.
+- Never swallow `DbUpdateConcurrencyException`.
+
+## Finish
+
+Run `dotnet test` and look at the logged SQL for each query you changed. Report: queries changed with before/after query counts, migrations added and whether they lose data, and concurrency handling added.

package/skills/ef-core-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My EF Core LINQ query throws 'could not be translated' when I call my own helper in Where",
+    "Loading orders with Include on lines and payments returns millions of rows in EF Core, should I use AsSplitQuery?",
+    "Two admins edit the same account and the last save wins, add optimistic concurrency with EF Core",
+    "How do I deploy dotnet ef migrations to production without calling Database.Migrate at startup?",
+    "Should this read-only EF Core endpoint use AsNoTracking or a projection?"
+  ],
+  "should_not_trigger": [
+    "Our ASP.NET Core middleware order breaks authentication, fix Program.cs",
+    "Refactor this C# service to use records and pattern matching",
+    "Write a Prisma migration for the new invoices table",
+    "This PostgreSQL index isn't being used for the orders query, read the EXPLAIN output",
+    "Configure Hibernate second-level cache for our Spring Boot JPA entities"
+  ]
+}

package/skills/email-deliverability/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: email-deliverability
+description: Gets email into the inbox instead of spam by setting up SPF, DKIM, DMARC and BIMI DNS records with alignment, splitting transactional and marketing mail onto separate subdomains and streams, choosing a sending provider, processing bounces and complaints, keeping lists clean and warming a new domain or IP. Use when mail lands in spam or bounces, a domain needs authenticating before sending, Gmail, Yahoo or Outlook bulk-sender rules must be met, or a new sending domain is about to go live.
+license: MIT
+compatibility: Any Agent Skills host. DNS checks use dig or nslookup; header checks need a raw message (.eml) or the provider's logs. Changes are made in the user's DNS host and email provider.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: network
+  kete-loom/requires: "dig"
+  kete-loom/owner: "Kete-org"
+---
+
+# Email deliverability
+
+Make mail provably come from the domain it claims, keep receipts and password resets away from the reputation of newsletters, and stop sending to people who bounce, complain or never engage.
+
+## Ground rules
+
+1. **Authenticate every sending domain** with SPF and DKIM, then DMARC. Gmail requires SPF or DKIM for everyone, and SPF, DKIM and DMARC (`p=none` allowed) for anyone sending more than 5,000 messages a day to personal Gmail accounts. Outlook.com (hotmail.com, live.com, outlook.com) requires SPF and DKIM to pass and DMARC to pass with alignment (`p=none` allowed) for senders of 5,000 or more messages from one `From:` domain, and rejects failures with `550 5.7.515`.
+2. **Alignment is what DMARC checks**: the `From:` domain must match the DKIM `d=` domain or the SPF (Return-Path) domain. A provider signing with its own domain passes DKIM but fails DMARC. Use custom DKIM and a custom return-path on your domain.
+3. **Separate streams.** Transactional mail (receipts, resets, alerts) and marketing mail use different subdomains (for example `mail.example.com` and `news.example.com`) and, where the provider supports it, different streams or IP pools. A bad campaign must never delay a password reset.
+4. **Never buy, rent or scrape lists** for marketing mail. Purchased lists contain spam traps and drive complaints; no technical setup fixes that.
+5. **Marketing mail needs one-click unsubscribe**: a `List-Unsubscribe` header with an HTTPS URL, `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058), and a visible link in the body. Honour it quickly (Google says within 48 hours; US CAN-SPAM allows at most 10 business days).
+6. **Watch the complaint rate.** Keep Gmail's user-reported spam rate in Postmaster Tools under 0.1% and never let it reach 0.3%.
+7. **Change DNS carefully.** Read the existing records before editing. A second SPF record, or a DMARC jump to `p=reject` before every sender is aligned, breaks real mail.
+
+## Diagnose first
+
+When the user says "our emails go to spam", collect before changing anything:
+
+1. The exact `From:` address, the provider(s) that send for that domain (app, marketing tool, CRM, helpdesk, Google Workspace or Microsoft 365), and daily volume per stream.
+2. Current records: `dig +short TXT example.com` (SPF), `dig +short TXT _dmarc.example.com`, `dig +short TXT <selector>._domainkey.example.com`, `dig +short MX example.com`.
+3. Raw headers of one message that landed in spam. Read `Authentication-Results:` for `spf=`, `dkim=`, `dmarc=` and the domains each checked.
+4. Data from Google Postmaster Tools and Microsoft SNDS if set up, plus the provider's bounce and complaint numbers.
+
+Then decide:
+
+| Finding | Fix |
+|---|---|
+| `dmarc=fail` with `dkim=pass` | DKIM signed by the provider's domain; set up custom DKIM on yours |
+| `spf=permerror` | More than 10 DNS lookups or two SPF records; merge and flatten (`references/dns-records.md`) |
+| All auth passes, still spam | Reputation or content: check complaint rate, list source, engagement, sudden volume jumps |
+| Bounces with `5.7.x` codes | Policy rejection: authentication or reputation; read the bounce text, it usually names the rule |
+| Only one mailbox provider affected | Check that provider's postmaster tools and its own requirements |
+
+## Set up a sending domain
+
+1. Choose subdomains per stream. List every service that will send as each one.
+2. Add the provider's DKIM records (2048-bit keys where offered; Gmail requires at least 1024) and its custom return-path or bounce domain (a CNAME or MX record).
+3. Publish one SPF record per domain name that sends, including only the services that use it: `v=spf1 include:<provider> ~all`. Record shapes in `references/dns-records.md`.
+4. Publish DMARC at `p=none` with an aggregate report address: `v=DMARC1; p=none; rua=mailto:dmarc@example.com`. Read the reports for a few weeks (2 to 4 is a common rule of thumb) to find every legitimate sender.
+5. Move to `p=quarantine`, then `p=reject` once reports show all real mail aligned. **Stop and ask the user** before each step.
+6. BIMI only after DMARC is at `quarantine` or `reject`; it needs an SVG Tiny PS logo and, for Gmail, a mark certificate (a VMC, or a CMC for a logo that is not trademarked). Other mailbox providers, including Apple Mail, set their own BIMI rules; check the provider's current documentation before buying a certificate. Treat it as a branding extra, not a deliverability fix.
+7. Set valid forward and reverse DNS (PTR) if you run your own sending IPs; hosted providers do this for you.
+
+## Choose a provider
+
+- Transactional: a provider with a dedicated transactional stream, webhooks for bounces and complaints, and per-message logs (for example Postmark, Amazon SES, SendGrid, Mailgun, Resend).
+- Marketing: a tool that handles consent, unsubscribes, suppression lists and one-click headers for you.
+- Shared IPs are right under roughly tens of thousands of messages a month; a dedicated IP needs steady volume to build a reputation. Ask the user for volume before recommending one.
+- Never send bulk mail through a personal Google Workspace or Microsoft 365 mailbox.
+
+## Bounces, complaints and list hygiene
+
+1. Subscribe to the provider's bounce and complaint webhooks (or SES notifications) and write them to a suppression table keyed by address.
+2. Hard bounce (`5.x.x`, unknown user): suppress immediately and permanently.
+3. Soft bounce (`4.x.x`, mailbox full, throttled): retry per the provider; suppress after repeated failures across several sends.
+4. Complaint (feedback loop, "report spam"): suppress from all marketing at once; it counts as an unsubscribe.
+5. Check suppression before every send, across every tool that mails the same domain.
+6. Use confirmed opt-in for sign-ups from public forms. Sunset marketing contacts with no opens or clicks for a long stretch (6 to 12 months is a common rule of thumb, not a provider rule) after a re-engagement attempt (opens are unreliable since Apple Mail Privacy Protection, so weight clicks).
+
+## Warm a new domain or IP
+
+1. Start with the most engaged recipients (recent sign-ups, active customers), not the whole list.
+2. Grow volume gradually, roughly doubling while bounce and complaint rates stay low; hold or drop back if they rise. Two to six weeks is a common rule of thumb, not a mailbox-provider rule; follow the sending provider's warm-up plan if it has one.
+3. Keep volume and timing steady; avoid one huge blast after weeks of silence.
+4. Send transactional mail from day one; it is high-engagement and builds reputation.
+
+## Never
+
+- Publish two SPF TXT records, or use `+all`.
+- Put a DMARC record at `p=reject` without reading reports first.
+- Hide or break the unsubscribe link, or require login to unsubscribe.
+- Re-import suppressed or bounced addresses into another tool.
+- Rotate domains or IPs to escape a bad reputation ("snowshoeing").
+
+## Report format
+
+```
+Domain(s): ...            Streams: transactional / marketing
+Auth status: SPF pass|fail (lookups n/10)  DKIM aligned yes|no  DMARC p=...
+Main problem: one sentence
+Fixes, in order: 1. ... (DNS record or setting, exact value) 2. ...
+Needs user decision: ...
+Re-test: send to a seed list and read Authentication-Results
+```
+
+Mailbox-provider rules change. Check Google's and Yahoo's sender guidelines and Microsoft's Outlook sender requirements before stating a threshold as current; links are in `references/dns-records.md`.

package/skills/email-deliverability/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Our password reset emails keep landing in Gmail spam, here are the headers showing dmarc=fail",
+    "Set up SPF, DKIM and DMARC for our new sending domain before we turn on Amazon SES",
+    "SPF check says permerror too many DNS lookups, how do I fix the record?",
+    "We send 20k newsletters a day, what do we need for the Gmail and Yahoo bulk sender requirements?",
+    "Plan a warm-up schedule for the brand new domain we bought for product emails",
+    "How should we handle hard bounces and spam complaints coming back from Postmark webhooks?"
+  ],
+  "should_not_trigger": [
+    "Write a five-step cold email sequence for CFOs at logistics companies",
+    "Turn our latest blog post into a weekly newsletter issue and three LinkedIn posts",
+    "Build the HTML template for our order confirmation email in React Email",
+    "Schedule our product announcement to post on X and LinkedIn via their APIs",
+    "Plan the launch campaign and channel budget for our new app"
+  ]
+}

package/skills/email-deliverability/references/dns-records.md

@@ -0,0 +1,85 @@
+# DNS record shapes
+
+Replace `example.com`, selectors and provider includes with the user's values. Always read existing records first.
+
+## SPF (RFC 7208)
+
+One TXT record at each name that appears as an envelope sender (Return-Path).
+
+```
+example.com.        TXT "v=spf1 include:_spf.google.com include:amazonses.com ~all"
+```
+
+- Only one `v=spf1` record per name. Two records is a `permerror`.
+- At most 10 DNS-querying mechanisms (`include`, `a`, `mx`, `ptr`, `exists`, `redirect`), counted recursively. Over 10 is a `permerror`, which counts as a fail.
+- To get under 10: move senders to subdomains (each subdomain has its own SPF), remove services no longer used, or replace an `include` with `ip4:`/`ip6:` ranges only if the provider publishes stable ones.
+- `~all` (softfail) is normal once DMARC is in place; `-all` is fine when the list is complete. Never `+all`.
+- A domain that never sends mail: `v=spf1 -all`.
+
+## DKIM
+
+The provider gives the selector and key, usually as a CNAME so it can rotate keys.
+
+```
+s1._domainkey.example.com.  CNAME  s1.domainkey.u123.wl.provider.net.
+s1._domainkey.example.com.  TXT    "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."
+```
+
+- Use 2048-bit RSA where offered. Long TXT values may need splitting into several quoted strings; most DNS hosts do this for you.
+- Check: `dig +short TXT s1._domainkey.example.com`. In a received message, `DKIM-Signature: d=` must be your domain for alignment.
+
+## DMARC (RFC 9989, which obsoletes RFC 7489)
+
+```
+_dmarc.example.com.  TXT  "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com; adkim=r; aspf=r"
+```
+
+| Tag | Meaning |
+|---|---|
+| `p` | `none` (monitor), `quarantine`, `reject` |
+| `sp` | policy for subdomains, defaults to `p` |
+| `rua` | where aggregate XML reports go; use a mailbox or a DMARC report service |
+| `pct` | RFC 7489 only: share of failing mail the policy applies to, default 100. RFC 9989 removed it (along with `rf` and `ri`) and added `t=y`, a test flag asking receivers to apply one policy level lower. Older receivers may still read `pct`; do not depend on it for rollout |
+| `adkim` / `aspf` | `r` relaxed (organisational domain match, the default) or `s` strict |
+
+Reports sent to a different domain need an authorisation record at that domain (`example.com._report._dmarc.reports.net TXT "v=DMARC1"`); report services set this up.
+
+Rollout: `p=none` for a few weeks (2 to 4 is a rule of thumb), then `p=quarantine`, then `p=reject`. Rolling out per subdomain with `sp=` is a safer stage than `pct`.
+
+## BIMI
+
+```
+default._bimi.example.com.  TXT  "v=BIMI1; l=https://example.com/bimi/logo.svg; a=https://example.com/bimi/vmc.pem"
+```
+
+- Requires DMARC at `quarantine` or `reject` on the organisational domain; Gmail also requires `pct=100` if `pct` is present.
+- `l=` is an HTTPS URL to an SVG Tiny PS file. `a=` is the PEM certificate (Gmail accepts a VMC or a CMC; other providers set their own rules).
+- Display is at the mailbox provider's discretion even when everything validates.
+
+## One-click unsubscribe headers (RFC 8058)
+
+```
+List-Unsubscribe: <https://example.com/unsub?t=opaque-token>, <mailto:unsub@example.com?subject=unsub>
+List-Unsubscribe-Post: List-Unsubscribe=One-Click
+```
+
+- The HTTPS endpoint must accept a POST with body `List-Unsubscribe=One-Click` and unsubscribe without further confirmation or login.
+- Both headers must be covered by the DKIM signature.
+- The token identifies the recipient and list; it must not be guessable or expose the address.
+
+## Useful checks
+
+```
+dig +short TXT example.com
+dig +short TXT _dmarc.example.com
+dig +short TXT default._bimi.example.com
+dig +short -x <sending-ip>        # reverse DNS (PTR)
+```
+
+## Sources
+
+- Gmail sender guidelines: https://support.google.com/a/answer/81126 and FAQ (48-hour unsubscribe): https://support.google.com/a/answer/14229414
+- Outlook.com high-volume senders (`550 5.7.515`): https://support.microsoft.com/en-us/outlook/fix-ndr-error-550-5-7-515-in-outlook-com
+- Gmail BIMI: https://knowledge.workspace.google.com/admin/security/set-up-bimi
+- SPF: https://www.rfc-editor.org/rfc/rfc7208 . DMARC: https://www.rfc-editor.org/rfc/rfc9989 . One-click unsubscribe: https://www.rfc-editor.org/rfc/rfc8058
+- CAN-SPAM: https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business

package/skills/energy-procurement/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: energy-procurement
+description: Commercial electricity and natural gas buying for offices, plants, warehouses and multi-site portfolios, covering how to read utility bills and tariffs (energy, demand, capacity and transmission charges), analysing 15-minute interval load data for load factor and peaks, comparing fixed-price, index and block-and-index supply contracts, running a supplier RFP on a like-for-like basis, layering purchases to manage price risk, and renewable options such as green tariffs, unbundled certificates and power purchase agreements. Use when a supply contract is up for renewal, a site's energy costs jumped, you are comparing supplier offers, or a sustainability target needs a renewable electricity plan, in a market where the customer can choose a supplier.
+license: MIT
+compatibility: Any Agent Skills host. Works from the user's bills, interval data and offers; market prices come from the user's broker, supplier or a market data service. Market rules differ by country, state and utility. Not financial, legal or trading advice.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Energy procurement
+
+Know what each site actually pays for and why, buy supply with a risk level the business chose on purpose, and compare offers on the same basis. Rules, charge names and who may sell to whom depend on the jurisdiction, so confirm them before you rely on any of this.
+
+## 0. Establish the market
+
+Ask, and stop until you have answers:
+
+1. Country and region, and for each site the utility (distribution company) and, where relevant, the grid or market operator (for example PJM, ERCOT, ISO-NE, NYISO, MISO, CAISO in the US; national markets in the UK and EU).
+2. Is the site in a market where the customer may choose a retail supplier for electricity, gas, or both? If not, the job is tariff optimisation with the utility, not a supply contract; use sections 1, 2 and 6 only.
+3. Current contracts: supplier, product type, price, start and end date, volume tolerance (swing) clauses, early termination terms.
+4. The business's risk appetite and budget certainty need, and who signs off (finance, procurement, a risk committee).
+
+Never state a regulated tariff rate, market rule, tax or incentive without checking the utility's current tariff sheet or the regulator's site; record source and date.
+
+## 1. Read the bills
+
+Collect 12 to 24 months of bills per site per fuel. Split every charge into:
+
+| Bucket | Electricity examples | Gas examples |
+|---|---|---|
+| Supply (energy) | kWh x energy price, often by time-of-use period | therms, MMBtu, or kWh x commodity price |
+| Capacity | capacity charge set by the site's load in the system peak hours (PJM's peak load contribution is one example) | n/a, or pipeline capacity |
+| Transmission | network charge, sometimes set by coincident peaks (ERCOT 4CP is one example) | transportation |
+| Distribution | utility delivery charge, kW demand charge on the monthly peak, customer charge | distribution, customer charge |
+| Taxes, levies, riders | renewable and efficiency riders, taxes | same |
+
+Record which buckets the supplier contract covers and which stay with the utility; offers that include different buckets cannot be compared directly. Check for billing errors: estimated reads, wrong rate class, wrong meter multiplier, tax charged on exempt use.
+
+## 2. Analyse the load
+
+1. Get 15-minute or hourly interval data (from the utility portal or meter data) for at least 12 months.
+2. Compute per site: annual kWh, peak kW, load factor (`average kW / peak kW`), on-peak versus off-peak split, and a monthly and hourly profile.
+3. Find the hours that set capacity and transmission charges in this market; quantify how much load the site was carrying in those hours.
+4. Note what can move: shiftable process load, on-site generation, storage, demand response programmes. Flag these as savings to evaluate, not promises.
+5. For gas: monthly usage against heating degree days, base load versus weather-driven load.
+
+A flat, high-load-factor profile gets better supply prices; a peaky profile pays for its shape.
+
+## 3. Choose the product structure
+
+| Product | What is fixed | Who carries price risk | Fits when |
+|---|---|---|---|
+| Fixed price (full requirements) | all-in supply price per unit for the term | supplier, priced in as a premium | budget certainty matters most, small team |
+| Index (pass-through) | supplier adder only; energy floats with the market index | customer | can absorb volatility, wants lowest expected cost |
+| Block and index | a fixed block (for example a set MW in on-peak hours); the rest floats | shared | large or predictable load, wants to hedge in stages |
+| Layered or hedged | tranches fixed at different times | shared, timed by the customer | has a policy and someone to execute it |
+
+Also check per offer: which charges are passed through rather than fixed, swing or bandwidth limits and the penalty for usage outside them, the material-change clause, credit requirements, term, and termination cost.
+
+## 4. Run a supplier RFP
+
+1. Send the same data to every supplier: sites, account and meter numbers, interval data, contract start date, term options, product structures wanted, which charges must be fixed or passed through, and payment and credit terms.
+2. Use a response template so each offer comes back on the same basis (price per unit by product and term, pass-through list, swing terms).
+3. Prices are usually valid for hours, not days; agree in advance who can accept, and get internal approval for a price ceiling before the pricing day.
+4. Normalise offers to an all-in cost per unit using the site's real load shape, and show it next to the contract risks.
+5. If a broker or consultant runs the RFP, ask how they are paid (fees embedded in the unit price are common) and put it in writing.
+
+## 5. Risk and hedging
+
+- Write a short procurement policy: target hedge percentage by year ahead (for example more hedged for the next 12 months than for year three), price triggers, who decides, and how results are reported.
+- Hedge by layering purchases over time rather than one day's price.
+- Report open (unhedged) volume and its exposure to a price move, using a scenario the user sets.
+- **Stop and say that a qualified energy adviser, treasury or risk function must decide** before any financial hedge, derivative, or a commitment above the user's sign-off limit. This skill does not give trading advice.
+
+## 6. Renewable options
+
+| Option | What you get | Watch |
+|---|---|---|
+| Utility green tariff | renewable supply via the utility | premium, additionality, term |
+| Supplier renewable product | supply plus certificates | which certificates, from where |
+| Unbundled certificates | RECs (US), Guarantees of Origin (EU), REGOs (UK), I-RECs elsewhere | market boundary and vintage rules for your reporting standard |
+| On-site generation | solar or other on site, owned or under a lease or PPA | roof, interconnection, net metering rules |
+| Physical or virtual PPA | long-term contract with a project; a virtual PPA is a financial contract for difference | long term, accounting treatment, basis and shape risk |
+
+Check the claim against the reporting standard the business uses (for example the GHG Protocol Scope 2 guidance; it has been under revision, so confirm the current version). Any PPA needs legal, accounting and treasury review before signing.
+
+## Rules
+
+- Never compare offers that fix different charges without normalising them first.
+- Never recommend accepting a price without the user's internal approval route confirmed.
+- Never present a forecast as a price; label every forward price with source, date and time.
+- Jurisdiction rules first: if you have not confirmed retail choice and the charge structure for the site, say so.
+
+## Report
+
+```
+Site | utility | rate class | annual kWh / therms | peak kW | load factor | current contract (product, price, end date)
+Bill split: supply x% | capacity x% | transmission x% | distribution x% | taxes x%
+Offers (normalised all-in per unit): supplier | product | term | price | pass-throughs | swing | notes
+Recommendation: product and term, hedge plan, renewable option, with risks
+Needs expert review: <hedges, PPA, contracts above limit, tariff questions>
+Sources: <tariff sheets, market data, dates>
+```

package/skills/energy-procurement/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our electricity supply contract for three plants in Ohio ends in March, should we go fixed price or block and index this time?",
+    "I have 12 months of 15-minute interval data for our warehouse, work out the load factor and what is driving our demand charges",
+    "Compare these four retail electricity supplier offers, some pass through capacity and transmission and some do not",
+    "Write a natural gas and power procurement policy with hedge targets for the next three years",
+    "We want 100% renewable electricity for our offices, compare a utility green tariff, unbundled RECs and a virtual PPA"
+  ],
+  "should_not_trigger": [
+    "Calculate our Scope 1 and Scope 2 greenhouse gas inventory for this year's sustainability report",
+    "Size a rooftop solar array and battery for my house and estimate the payback",
+    "Write a Python job that pulls smart meter readings from our IoT gateway into TimescaleDB",
+    "Our supplier sent a batch of out-of-spec castings, open a nonconformance and start the root cause",
+    "Find a reliable truckload carrier for our new Houston to Denver lane"
+  ]
+}