@ketecode/loom 0.0.0-stage → 0.2.0

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/document-processing/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: document-processing
+description: Pipelines for PDFs and scanned paperwork built on open tools - triage each file as born-digital, scanned or mixed, pull text and tables with pdfplumber or pdftotext, add a searchable text layer with OCRmyPDF and Tesseract language packs, split, merge, rotate, decrypt and repair with qpdf, read and fill AcroForm fields with pypdf or pdftk, redact so the underlying text and metadata are truly gone and prove it, and translate a document while keeping its layout. Use when someone has a folder of PDFs or scans to extract data from, needs a scanned contract made searchable, wants a PDF form filled from a spreadsheet, or must hand over a redacted document that has to survive copy-paste and text extraction.
+license: MIT
+compatibility: Any Agent Skills host. Uses Python 3 with pdfplumber and pypdf, plus the qpdf, ocrmypdf, tesseract (with the needed language data), pdftotext/pdfinfo (poppler-utils) and optionally pdftk CLIs. Redaction examples use PyMuPDF, which is AGPL-licensed.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python3, qpdf, ocrmypdf, tesseract, pdftotext"
+  kete-loom/owner: "Kete-org"
+---
+
+# Document processing
+
+Treat every document as evidence: never change the original, keep each step's output, and check results against the page images, not just the extracted text. Command and code detail is in `references/extraction-and-ocr.md`, `references/forms-and-conversion.md` and `references/redaction.md`.
+
+## 0. Before you start
+
+1. Copy inputs to `work/in/` and treat them as read-only. Outputs go to `work/out/`.
+2. Ask the user what the result is for (search, a spreadsheet, a filled form, a redacted copy for disclosure, a translation) and the languages in the documents.
+3. **Sensitive content** (IDs, health, financial, legal): confirm the user may process it and that no cloud OCR, translation or AI service will be used without their approval. Default to local tools.
+4. Do not open files from untrusted sources with tools that execute embedded content; work with command-line tools and libraries, not by opening JavaScript-enabled viewers.
+
+## 1. Triage each file
+
+Run `pdfinfo file.pdf` (pages, encryption, PDF version, tagged or not) and `pdffonts file.pdf`, then sample text with `pdftotext -f 1 -l 3 -layout file.pdf -`.
+
+| Finding | Class | Next step |
+|---|---|---|
+| Text comes out readable, fonts listed | Born-digital | Extract directly (step 2) |
+| No text, no fonts, pages are images | Scanned | OCR first (step 3) |
+| Some pages have text, others not | Mixed | OCR with skip mode for pages that already have text |
+| Text is garbled (wrong glyphs, `(cid:123)`) | Broken font encoding | OCR with force mode, or redo |
+| `qpdf --check` reports damage | Damaged | Repair with `qpdf in.pdf repaired.pdf`, then re-triage |
+| Encrypted | Protected | Decrypt with `qpdf --decrypt` only with the password and permission from the user |
+
+## 2. Extract text and tables (born-digital)
+
+1. Plain text in reading order: `pdftotext -layout` for column-preserving text, or pdfplumber `page.extract_text()` for per-page control.
+2. Tables: pdfplumber `page.extract_tables()` with explicit `table_settings` (lines strategy for ruled tables, text strategy for whitespace tables). Crop to the table region with `page.crop(bbox)` when a page has more than one table.
+3. Keep provenance on every row: file, page number and, for tables, the bounding box.
+4. Validate: row counts per page, column totals against the printed totals, and a manual spot check of at least three rows against the page image. Report any mismatch rather than "fixing" numbers.
+
+## 3. OCR scans
+
+1. Run OCRmyPDF with the right languages (`-l eng+fra`; install the Tesseract language data first, check with `tesseract --list-langs`).
+2. For phone photos or skewed scans add `--rotate-pages --deskew --clean`. These cannot be combined with redo mode.
+3. For mixed files use skip mode (`--skip-text`, or `--mode skip` in OCRmyPDF 17+); for an existing bad text layer use `--redo-ocr` (`--mode redo`); `--force-ocr` (`--mode force`) rasterises everything and loses vector quality.
+4. Write PDF/A for archiving (`--output-type pdfa`) and a `--sidecar out.txt` for the plain text.
+5. Check quality: sample pages, compare OCR text with the image, and note low-confidence areas (handwriting, stamps, tables). OCR is never 100% accurate; say so in the report and keep the images as the source of truth.
+
+## 4. Convert, split, merge, rotate
+
+Use qpdf for structural work (no re-rendering, so quality is kept): `--pages` to select, split or merge, `--rotate`, `--linearize` for web viewing, `--split-pages` for one file per page. Office formats to PDF via `libreoffice --headless --convert-to pdf` if installed. Recipes in `references/forms-and-conversion.md`.
+
+## 5. Fill forms
+
+1. List the fields first (`pypdf` `reader.get_fields()` or `pdftk in.pdf dump_data_fields_utf8`) and map them to the user's data. **Show the user the mapping** before filling.
+2. Fill with pypdf (`writer.update_page_form_field_values`) or pdftk (`fill_form data.fdf output out.pdf`), one output per record.
+3. Checkboxes and radio buttons need their export value (often `/Yes` or `/On`), not `True`.
+4. Flatten (`pdftk ... flatten`, or render) only when the user wants a non-editable copy; keep the unflattened version.
+5. XFA forms (dynamic forms from Adobe LiveCycle) are not AcroForms; most open tools cannot fill them. Stop and tell the user.
+6. Open each output and check a few fields by eye.
+
+## 6. Redact (must be real)
+
+Drawing a black box over text does **not** redact it: the text stays in the content stream and is copied, searched and extracted. Follow `references/redaction.md` exactly:
+
+1. Find every occurrence (search the text layer and the OCR layer; patterns for IDs, emails, phone numbers; ask the user for names and terms).
+2. Apply true redaction that removes the text, vector graphics and image pixels under each area (PyMuPDF `add_redact_annot` then `apply_redactions`), or rasterise the pages and re-OCR the result.
+3. Remove metadata, XMP, attachments, annotations, form field values, bookmarks and earlier revisions (incremental updates) by rewriting the file.
+4. **Verify**: extract all text from the output and search for every redacted term; inspect metadata; check that the file has no incremental updates left. Any hit means the redaction failed.
+5. A person must review redactions before disclosure. Legal, court or regulatory redaction rules (what must be withheld, how it is marked) are outside this skill; the user's legal team decides.
+
+## 7. Translate with layout
+
+1. Extract text per block with its position, font size and page (pdfplumber words or PyMuPDF blocks).
+2. Translate block by block, with the tool or service the user approves; keep numbers, names, codes and dates unchanged and give the translator a glossary.
+3. Rebuild: either an overlay PDF that writes translated text into each block's box (shrink font to fit, flag blocks that overflow) or a bilingual table (source, translation, page) when layout matters less than accuracy.
+4. Fonts must cover the target script (for example Noto fonts for Bengali, Arabic, CJK); check that no characters render as boxes. Complex scripts need a shaping-capable text engine.
+5. Machine translation of legal, medical or official documents needs review by a qualified translator before use; certified translations are out of scope.
+
+## Never
+
+- Never modify or delete the original files.
+- Never present OCR or extracted numbers as exact without a spot check.
+- Never send documents to an online service without the user's explicit approval.
+- Never call a document redacted until the verification step passes.
+
+## Report back
+
+```
+Files: n (born-digital / scanned / mixed / damaged)
+Outputs: <paths>   Tools and versions: ...
+Extraction: rows or pages extracted, spot checks done, mismatches
+OCR: languages, pages OCRed, known weak areas
+Redaction: terms and patterns, hits after verification (must be 0), metadata cleared
+Needs a human: legal review of redactions, translation review, unreadable pages
+```

package/skills/document-processing/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Pull the transaction tables out of these 200 bank statement PDFs into one CSV",
+    "Make this folder of scanned contracts searchable with OCR, some are in French",
+    "Fill this PDF application form for each of the 50 rows in our spreadsheet",
+    "Redact every name and account number from this PDF and prove the text can't be copied back out",
+    "Translate this German PDF brochure into English but keep the layout of each page",
+    "The text I extract from this PDF comes out as (cid:34) gibberish, how do I get real text"
+  ],
+  "should_not_trigger": [
+    "Create a Word document report with a table of contents and page numbers",
+    "Translate the app's UI strings into French and German with message catalogs",
+    "Write the user guide for our CLI tool",
+    "Build a RAG pipeline that chunks and embeds our product manuals",
+    "Normalise the Bengali text in our search index so the same word always matches"
+  ]
+}

package/skills/document-processing/references/extraction-and-ocr.md

@@ -0,0 +1,71 @@
+# Extraction and OCR
+
+## Triage commands
+
+```bash
+pdfinfo in.pdf                      # pages, encryption, producer, PDF version
+pdffonts in.pdf                     # no fonts => likely scanned
+pdftotext -f 1 -l 3 -layout in.pdf - | head -50
+qpdf --check in.pdf                 # structural problems
+pdfimages -list in.pdf | head       # image resolution per page (OCR needs ~300 dpi)
+```
+
+## Text with pdfplumber
+
+```python
+import pdfplumber, json
+rows = []
+with pdfplumber.open("work/in/report.pdf") as pdf:
+    for i, page in enumerate(pdf.pages, start=1):
+        text = page.extract_text(layout=False) or ""
+        rows.append({"page": i, "text": text})
+json.dump(rows, open("work/out/report.text.json", "w"), ensure_ascii=False, indent=1)
+```
+
+Words with positions (for layout-aware work): `page.extract_words(keep_blank_chars=False, use_text_flow=True)` returns `x0, top, x1, bottom, text`.
+
+## Tables with pdfplumber
+
+```python
+ruled = {"vertical_strategy": "lines", "horizontal_strategy": "lines"}
+whitespace = {"vertical_strategy": "text", "horizontal_strategy": "text", "snap_tolerance": 3}
+
+with pdfplumber.open("work/in/statement.pdf") as pdf:
+    page = pdf.pages[0]
+    region = page.crop((0, 120, page.width, 700))   # x0, top, x1, bottom in PDF points
+    for table in region.extract_tables(ruled):
+        for row in table:
+            print(row)
+```
+
+Debug a table: `page.to_image(resolution=150).debug_tablefinder(ruled).save("debug.png")` and look at the detected lines.
+
+Tips:
+- Header rows that repeat on every page: drop them after the first page by matching the header.
+- Cells that wrap onto two lines become `"line1\nline2"`; join them, do not split into rows.
+- Numbers: strip thousands separators according to the document's locale (1.234,56 vs 1,234.56); keep the original string next to the parsed value.
+
+## OCRmyPDF
+
+```bash
+tesseract --list-langs                         # confirm language data is installed
+ocrmypdf -l eng --rotate-pages --deskew --clean --output-type pdfa --sidecar out.txt in.pdf out.pdf
+ocrmypdf -l eng+deu --skip-text in.pdf out.pdf     # mixed: only OCR pages without text
+ocrmypdf -l eng --redo-ocr in.pdf out.pdf          # replace a bad hidden text layer
+ocrmypdf -l ben --force-ocr in.pdf out.pdf         # rasterise and OCR everything
+```
+
+- OCRmyPDF 17 added `--mode skip|redo|force`; the legacy flags still work.
+- `--clean` needs the `unpaper` program installed; it only cleans the image Tesseract sees, not the output page (that is `--clean-final`).
+- `--redo-ocr` cannot be combined with `--deskew`, `--rotate-pages` or `--clean`.
+- Tesseract language codes are ISO 639-2 style (`eng`, `fra`, `deu`, `ben`, `hin`, `ara`, `chi_sim`, `jpn`). Choose `script/` models (for example `script/Devanagari`) when the language is unknown but the script is.
+- Very low-resolution scans: upscale is no substitute for a rescan at 300 dpi; tell the user.
+
+## Plain Tesseract on images
+
+```bash
+tesseract page.png out -l eng --psm 6       # writes out.txt; --psm 6 = single uniform block
+tesseract page.png out -l eng tsv           # word-level confidence in out.tsv
+```
+
+Use the `conf` column of the TSV to flag words under about 60 for human checking.

package/skills/document-processing/references/forms-and-conversion.md

@@ -0,0 +1,69 @@
+# Forms and structural conversion
+
+## qpdf
+
+```bash
+qpdf in.pdf repaired.pdf                                   # rewrite, fixes many damaged files
+qpdf --decrypt --password-file=pw.txt locked.pdf open.pdf  # only with the owner's permission; a file keeps the password out of shell history
+qpdf --empty --pages a.pdf b.pdf 1-3 -- merged.pdf          # all of a, pages 1-3 of b
+qpdf in.pdf --pages . 5-10 -- part.pdf                      # extract pages
+qpdf --split-pages in.pdf page-%d.pdf                       # one file per page
+qpdf in.pdf rotated.pdf --rotate=+90:2,4                    # rotate pages 2 and 4 by 90 degrees clockwise
+qpdf --linearize in.pdf web.pdf                             # fast web view
+qpdf --qdf --object-streams=disable in.pdf inspect.pdf      # human-readable objects for debugging
+```
+
+Office documents to PDF (if LibreOffice is installed):
+
+```bash
+libreoffice --headless --convert-to pdf --outdir work/out work/in/*.docx
+```
+
+## List form fields
+
+```bash
+pdftk form.pdf dump_data_fields_utf8
+```
+
+```python
+from pypdf import PdfReader
+reader = PdfReader("form.pdf")
+for name, f in (reader.get_fields() or {}).items():
+    print(name, f.get("/FT"), f.get("/V"), f.get("/_States_", ""))   # /_States_ lists checkbox values
+```
+
+If `get_fields()` is empty but the PDF looks like a form, it is either flat (no fields) or XFA. Check with `acro = reader.trailer["/Root"].get("/AcroForm")` then `acro is not None and "/XFA" in acro.get_object()`. Report which.
+
+## Fill with pypdf
+
+```python
+from pypdf import PdfReader, PdfWriter
+reader = PdfReader("form.pdf")
+writer = PdfWriter(clone_from=reader)
+values = {"FullName": "Ama Mensah", "Date": "2026-03-02", "Agree": "/Yes"}
+for page in writer.pages:
+    writer.update_page_form_field_values(page, values, auto_regenerate=False)
+writer.set_need_appearances_writer(True)   # ask viewers to regenerate appearances
+with open("filled.pdf", "wb") as fh:
+    writer.write(fh)
+```
+
+Check the pypdf version's docs: the signature of `update_page_form_field_values` has gained options (such as `flatten`) over releases.
+
+## Fill with pdftk
+
+Write an FDF or XFDF with the values, then:
+
+```bash
+pdftk form.pdf fill_form data.xfdf output filled.pdf            # keeps fields editable
+pdftk form.pdf fill_form data.xfdf output filled_flat.pdf flatten
+```
+
+Use `need_appearances` if the viewer shows empty fields after filling.
+
+## Batch filling from a CSV
+
+1. Read the CSV with the csv module (UTF-8, keep leading zeros as strings).
+2. Map CSV columns to field names with an explicit dict the user approved.
+3. One output per row named from a key column, sanitised to a safe filename.
+4. Log each row: output path, fields filled, fields missing.

package/skills/document-processing/references/redaction.md

@@ -0,0 +1,61 @@
+# Redaction that holds up
+
+A redaction has failed if any redacted value can be recovered by selecting, copying, searching, extracting text, reading metadata, opening an earlier revision or lifting an overlay. Check every one.
+
+## 1. Find targets
+
+```python
+import fitz, re   # PyMuPDF (AGPL; confirm the licence suits the user)
+patterns = [r"\b\d{3}-\d{2}-\d{4}\b", r"[\w.+-]+@[\w-]+\.[\w.]+"]
+terms = ["Ama Mensah", "Account 0012345678"]   # from the user
+doc = fitz.open("work/in/case.pdf")
+hits = []
+for page in doc:
+    text = page.get_text()
+    found = set(terms) | {m.group(0) for p in patterns for m in re.finditer(p, text)}
+    for t in found:
+        for rect in page.search_for(t):
+            hits.append((page.number + 1, t, rect))
+print(len(hits), "hits")
+```
+
+Scanned pages have no text to search: OCR them first, then search the OCR layer, and redact the image region as well as the hidden text.
+
+Show the user the hit list (page, term, count) before applying.
+
+## 2. Apply
+
+```python
+for page_no, _term, rect in hits:                    # the approved hit list from step 1
+    doc[page_no - 1].add_redact_annot(rect, fill=(0, 0, 0))
+for page in doc:
+    page.apply_redactions(images=fitz.PDF_REDACT_IMAGE_PIXELS)   # removes text and the image pixels under each box; be explicit, defaults changed across versions
+doc.set_metadata({})
+doc.del_xml_metadata()
+for name in doc.embfile_names():
+    doc.embfile_del(name)
+doc.save("work/out/case.redacted.pdf", garbage=4, deflate=True, clean=True)   # full rewrite, no incremental update
+```
+
+Also remove, where present: form field values, annotations and comments, bookmarks that quote redacted text, and document-level JavaScript.
+
+Stronger alternative when the layout does not need to stay searchable: rasterise each page to an image at 200 to 300 dpi after drawing the boxes, build a new PDF from the images, then OCR it if search is needed. This leaves no original text objects at all.
+
+## 3. Verify (all must pass)
+
+```bash
+pdftotext work/out/case.redacted.pdf - | grep -i -E "Ama Mensah|0012345678|[0-9]{3}-[0-9]{2}-[0-9]{4}" && echo "FAIL: text still present"
+pdfinfo work/out/case.redacted.pdf            # author, title, subject, keywords cleared
+exiftool work/out/case.redacted.pdf           # if installed: XMP and other metadata
+grep -c "%%EOF" work/out/case.redacted.pdf    # more than 1 suggests incremental updates remain (a linearized file also has 2)
+qpdf --check work/out/case.redacted.pdf
+```
+
+pdftotext does not read annotation or form-field text: also list fields with pypdf `get_fields()` and annotations with PyMuPDF `page.annots()` and confirm none hold a redacted value.
+
+Then open the output, select all text on a redacted page, and paste it into a text file; search again. Check a few redacted areas zoomed in for half-covered characters.
+
+## 4. Hand-off
+
+- Report: terms and patterns used, hits found, hits after verification (must be zero), what metadata was removed.
+- A person must review every redacted page before release. What must legally be withheld, and how redactions must be labelled (for example exemption codes), is decided by the user's legal or records team, not by this process.

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