Good First Issues

Good First Issues

Small, self-contained, genuinely useful. Live lists: good first issue · help wanted.

Setup takes about five minutes: Getting Started. The rules a change has to respect: Contributing.

---

Start here if you have never opened the codebase

Run the first model benchmark: #153

No need to understand the codebase, and it answers the project's central open question.

The harness is done: a 534-document labelled corpus, a scorer, and pnpm bench:models, which runs each model with and without the pattern pass and measures quality per category, tokens and cost per document, and throughput. What is missing is someone running it on real models, committing the results, and writing up what it found, including if the claim does not hold.

BENCH_MODELS=… pnpm bench:models --limit 20    # see the cost per document first
pnpm bench:models
pnpm bench:charts

How it works and what to commit: Testing and Benchmarks §6. It costs real API money, so start with --limit.

Review corpus labels: #144

The corpus labels come from how each document was generated and were cross-checked by a model from another family, but no person has reviewed them yet. Reviewing a slice, and fixing or flagging bad labels, makes every benchmark number trustworthy.

---

Start here if you work on the frontend

Touch: draw a region with a finger: #45

Region drawing uses mouse events, so on a tablet or phone the tool can be selected and does nothing. Manual regions are the fallback for everything detection misses. Done looks like: pointer events so drawing, moving and resizing work with a finger, with handles sized for a finger, on both the image and PDF canvases.

---

Start here if you speak a language other than English

Locale-aware detectors: #43

Keyword anchors (DOB, Account), street suffixes and name heuristics are English, and so are the prompts. On other languages the pattern pass finds structured formats and little else, silently. A contribution for one language you actually speak is useful on its own. The corpus already contains de-DE, fr-FR, es-ES and en-IN documents, so pnpm corpus:score can measure the before and after.

---

Start here if you use a screen reader, or care about contrast

An accessibility pass: #42

The attributes are there. What remains cannot be done by reading the code: whether reviewing a document with a screen reader is genuinely workable (announcements at the right moments, not drowning the user on a page of 80 suggestions), and measuring the dark theme's contrast against WCAG.

---

Start here if you like writing tests

Browser end-to-end tests: #35

pnpm smoke never touches the editor. Playwright tests per format that accept and reject on the canvas and in the inspector, draw a region, search and Redact all, create a rule, approve a (scripted) Hush card, export, download, and assert the accepted values are not in the bytes. That last assertion is the one that matters.

Fix and test the small-XLSX misread

loadWorkbook in lib/documents/xlsx/extract.ts slices Node's shared buffer pool at the wrong offset for workbooks under 4 KB, so they are intermittently read as corrupt (Troubleshooting). A test that loads a tiny workbook many times, plus a correct copy, would close it. (Not filed as an issue yet, so open one first.)

---

A contribution that needs no code at all

A fixture from a format's messier corners

A deck written by Keynote, a mailing-list digest, a CSV a bank exported, a mailbox from an unusual client. Every parser bug worth fixing came from a real file shaped in a way nobody predicted. Make it synthetic (never real personal data) and open an issue with it.

---

The one with the most leverage per line of code

Preserve the PDF text layer: #40

Not a first issue: hard and valuable. Content-stream surgery instead of rasterising the page, behind the same verification gate as everything else. Nearly right means leaking.

---

Before you open the PR

pnpm lint && pnpm typecheck && pnpm test && pnpm build

One concern per PR; explain why in the commit body; and if it moves the version, add a changelog.d/ fragment in the same PR. Checklist: Contributing.