@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/docker-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a Dockerfile for our Express API that doesn't run as root",
+    "Our Docker image is 1.8GB, can you get it down with a multi-stage build?",
+    "Every docker build reinstalls all the npm packages even when I only change one source file",
+    "Set up a compose.yaml so I can run the app with Postgres and Redis locally",
+    "We pass the NPM_TOKEN as a build arg, how do we stop it ending up in the image?"
+  ],
+  "should_not_trigger": [
+    "Add liveness and readiness probes to our Kubernetes Deployment",
+    "Write a Terraform module for an ECR repository and an ECS service",
+    "Review this Dockerfile and the Helm chart for security problems before we ship",
+    "Create a GitHub Actions workflow that runs the tests on every pull request",
+    "Roll back the payments deployment in the cluster to the previous ReplicaSet"
+  ]
+}

package/skills/docker-patterns/references/dockerfiles.md

@@ -0,0 +1,105 @@
+# Dockerfile templates
+
+Starting points. Adjust versions, paths and commands to the project; don't paste blindly.
+
+## Node.js (npm)
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM node:22-bookworm-slim AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN --mount=type=cache,target=/root/.npm npm ci
+
+FROM deps AS build
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+FROM node:22-bookworm-slim
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --chown=node:node package.json ./
+USER node
+EXPOSE 3000
+CMD ["node", "dist/server.js"]
+```
+
+## Python (pip)
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim AS build
+WORKDIR /app
+RUN python -m venv /opt/venv
+ENV PATH=/opt/venv/bin:$PATH
+COPY requirements.txt .
+RUN --mount=type=cache,target=/root/.cache/pip pip install -r requirements.txt
+
+FROM python:3.12-slim
+ENV PATH=/opt/venv/bin:$PATH PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+RUN useradd --create-home --uid 10001 app
+WORKDIR /app
+COPY --from=build /opt/venv /opt/venv
+COPY --chown=app:app . .
+USER app
+EXPOSE 8000
+CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app.wsgi:application"]
+```
+
+## Go (static binary)
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM golang:1.23 AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN --mount=type=cache,target=/go/pkg/mod go mod download
+COPY . .
+RUN --mount=type=cache,target=/go/pkg/mod --mount=type=cache,target=/root/.cache/go-build \
+    CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app ./cmd/app
+
+FROM gcr.io/distroless/static-debian12:nonroot
+COPY --from=build /out/app /app
+USER nonroot:nonroot
+EXPOSE 8080
+ENTRYPOINT ["/app"]
+```
+
+## Java (Maven, Spring Boot style fat jar)
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM eclipse-temurin:21-jdk AS build
+WORKDIR /src
+COPY pom.xml mvnw ./
+COPY .mvn .mvn
+RUN --mount=type=cache,target=/root/.m2 ./mvnw -q dependency:go-offline
+COPY src src
+RUN --mount=type=cache,target=/root/.m2 ./mvnw -q package -DskipTests
+
+FROM eclipse-temurin:21-jre
+RUN useradd --uid 10001 app
+WORKDIR /app
+COPY --from=build /src/target/*.jar app.jar
+USER app
+EXPOSE 8080
+ENTRYPOINT ["java", "-jar", "/app/app.jar"]
+```
+
+## Build-time secret example
+
+```dockerfile
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
+```
+
+```sh
+docker build --secret id=npmrc,src=$HOME/.npmrc -t app:dev .
+```
+
+## Notes
+
+- `# syntax=docker/dockerfile:1` opts into the current stable Dockerfile frontend, which `--mount` needs on older engines.
+- Version tags above are examples. Use the versions the project already targets.
+- A distroless or `scratch` image has no shell: `docker exec ... sh` won't work, and a `HEALTHCHECK` needs a binary you add yourself.

package/skills/e2e-testing-playwright/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: e2e-testing-playwright
+description: Writes and maintains Playwright Test end-to-end suites for web apps, using role-based locators, web-first assertions that auto-wait, saved storageState for login, page.route network mocks, isolated per-test data, traces for flaky runs and a sharded CI job. Use when adding or fixing browser end-to-end tests with Playwright, setting up playwright.config, or making an existing Playwright suite reliable in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node 18+ and the project's package manager; browsers install with npx playwright install.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx"
+  kete-loom/owner: "Kete-org"
+---
+
+# End-to-end testing with Playwright
+
+An end-to-end test drives the real app through a real browser, the way a user would. It is slow and costly to maintain, so write few of them, for the journeys that make money or lose data, and make each one deterministic.
+
+## 0. Before you start
+
+1. Look for an existing setup: `playwright.config.ts`, an `e2e/` or `tests/` folder, `@playwright/test` in `package.json`. Follow its conventions (folder, fixtures, naming, base URL) instead of creating a parallel setup.
+2. If there is none, run `npm init playwright@latest` (or the project's package manager equivalent) and accept TypeScript. Then read `references/config-and-ci.md` for a config to start from.
+3. Find out how the app starts locally and what test data it needs. If the app needs a database or third-party sandbox you cannot reach, **stop and ask the user** how they want it provided.
+4. Run the existing suite once (`npx playwright test`) and record the result before changing anything.
+
+## 1. Choose what to cover
+
+- List the critical journeys: sign up, log in, the core create/edit flow, checkout or payment, anything with irreversible effects.
+- One test per journey outcome. Cover the happy path plus the one or two failure paths a user really hits (invalid card, expired session).
+- Push everything else down: validation rules, formatting and edge cases belong in unit or component tests.
+
+## 2. Locators: how a user finds things
+
+Use, in order of preference:
+
+1. `page.getByRole('button', { name: 'Save' })`: role plus accessible name.
+2. `page.getByLabel('Email')`, `getByPlaceholder`, `getByText`, `getByAltText`, `getByTitle`.
+3. `page.getByTestId('cart-total')`: only when there is no user-facing handle. The attribute defaults to `data-testid` (change it with `use.testIdAttribute`).
+
+Never use CSS chains tied to layout (`div > div:nth-child(3)`), generated class names, or XPath. Narrow with `locator.filter({ hasText })` or by chaining from a parent region (`page.getByRole('dialog').getByRole('button', { name: 'Confirm' })`). If a role locator can't find an element, the element is probably inaccessible: report that, don't paper over it with a test id.
+
+## 3. Waiting: never sleep
+
+- Actions (`click`, `fill`, `check`) wait for the element to be visible, stable, enabled and able to receive events.
+- Assert with web-first assertions that retry until timeout: `await expect(locator).toBeVisible()`, `toHaveText`, `toHaveValue`, `toHaveURL`, `toHaveCount`.
+- Never write `page.waitForTimeout(...)` or a fixed sleep. Never `expect(await locator.textContent()).toBe(...)`: that reads once and does not retry.
+- For a non-DOM condition, use `await expect.poll(() => fetchStatus()).toBe('done')`.
+- To wait for a specific request, start `page.waitForResponse(...)` before the action that triggers it.
+
+## 4. Isolation and data
+
+- Each test gets a fresh browser context: no shared cookies or storage. Keep it that way; never make test B depend on test A.
+- Create the data a test needs in the test (through the app's API with the `request` fixture, or a seed helper), with unique values (`order-${test.info().testId}` or a random suffix), so tests can run in parallel and on retry.
+- Clean up in fixture teardown, or use a disposable database per run. Never point tests at production.
+- Put shared setup in custom fixtures with `test.extend`, not in `beforeAll` blocks that leak state.
+
+## 5. Authentication
+
+Log in once and reuse the state. Use a setup project that logs in through the UI, waits for proof of login, and saves `page.context().storageState({ path: 'playwright/.auth/user.json' })`; testing projects set `dependencies: ['setup']` and `use: { storageState: 'playwright/.auth/user.json' }`. Add `playwright/.auth` to `.gitignore`: it holds live cookies. For several roles, save one file per role. Tests of the login form itself start with an empty state: `test.use({ storageState: { cookies: [], origins: [] } })`.
+
+## 6. Network mocking
+
+Mock only what you don't own or can't control (payment provider, maps, flaky third parties, rare error responses):
+
+```ts
+await page.route('**/api/rates', route =>
+  route.fulfill({ status: 503, json: { error: 'unavailable' } }));
+```
+
+- Use `route.fulfill` for canned responses, `route.abort()` to simulate network failure, `route.continue()` to modify a request in flight.
+- Keep at least one unmocked journey against your own backend, or the suite proves nothing about integration.
+- For larger fixtures, record a HAR with `page.routeFromHAR(path, { update: true })` once and replay it.
+
+## 7. Flaky tests
+
+1. Reproduce: `npx playwright test path/to/spec.ts --repeat-each=20 --workers=4`.
+2. Read the trace: config `trace: 'on-first-retry'` (or `--trace on`), then `npx playwright show-trace <trace.zip>`. Check the action log, DOM snapshots, network and console at the failing step.
+3. Fix the cause: a missing web-first assertion, shared data, an animation, a race with a request, an un-awaited promise. Retries hide flakiness; they don't fix it.
+4. In CI, `--fail-on-flaky-tests` turns "passed on retry" into a failure when the team wants zero tolerance.
+
+## 8. CI
+
+Run with retries 2 and 1 worker per shard on CI, upload the HTML report and traces as artifacts, and shard with `--shard=1/4` for large suites. A ready workflow and config are in `references/config-and-ci.md`.
+
+## Rules
+
+- Never commit `test.only` (set `forbidOnly: !!process.env.CI`).
+- Never add a sleep, a raw `setTimeout`, or a huge timeout to make a test pass.
+- Never weaken or delete an assertion to get green; find out why it failed.
+- Never put real credentials in test files; read them from environment variables.
+- Visual snapshots (`toHaveScreenshot`) only for stable, important screens, generated on the same OS and browser as CI.
+
+## Report back
+
+End with: tests added or changed (file and title), the exact command run, pass/fail/flaky counts, and anything not covered (for example "payment provider mocked, real sandbox not exercised").

package/skills/e2e-testing-playwright/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write a Playwright test for the signup and onboarding flow",
+    "Our Playwright tests keep logging in through the UI before every test, make them reuse the session",
+    "Set up Playwright in this Next.js repo and add an e2e test for checkout, with a GitHub Actions job",
+    "Mock the exchange-rate API in my Playwright spec so I can test the error banner",
+    "Replace the waitForTimeout calls in our playwright specs with proper assertions"
+  ],
+  "should_not_trigger": [
+    "Click through the staging site and tell me what's broken before the demo",
+    "The nightly end-to-end run failed again, figure out whether it's the app or the tests and stabilise it",
+    "Look at the tests in this pull request and tell me which cases are missing",
+    "Write unit tests for the price formatting helper with Vitest",
+    "Our coverage is 41%, help me add tests where it actually matters"
+  ]
+}

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"
+  ]
+}