# skiffr docs

> Open-source job application autofill that learns from your corrections. Early development, not released.

# Introduction

URL: https://docs.skiffr.findmalek.engineer/docs
Markdown: https://docs.skiffr.findmalek.engineer/docs/index.md

> What Skiffr is made of and where to find things.

skiffr is an open-source Chrome extension that fills job applications from your own profile, and never submits anything for you. A dashboard keeps your profile, answers, a job queue and stats. You host the api and the database yourself. It is in early development and not released: the extension detects forms, asks, fills them and learns from your edits today, with the limits listed in [how skiffr learns](https://docs.skiffr.findmalek.engineer/docs/learning.md).

The repo is a turborepo with a landing page, a dashboard with login, an api, and the extension, wired to postgres with pgvector, auth and typed rpc. Edit these pages in `apps/docs/content/docs`, they are plain mdx.

## What is in the repo

- `apps/web`: the landing page. It only talks to the api
- `apps/dashboard`: profile, answers, queue, stats, Gmail, sources and tokens. It only talks to the api
- `apps/api`: orpc on bun. The only app that touches the database, auth and providers
- `apps/extension`: the Chrome extension (WXT, React, Manifest V3). It calls the api with a token
- `apps/e2e`: the Playwright suite that drives the built extension
- `apps/docs`: this site
- `packages/*`: shared code, see [structure](https://docs.skiffr.findmalek.engineer/docs/structure.md)

## Where to go next

- [Setup](https://docs.skiffr.findmalek.engineer/docs/setup.md): Install, start postgres, run the apps.

- [Environment](https://docs.skiffr.findmalek.engineer/docs/environment.md): Every key in the root `.env`.

- [Structure](https://docs.skiffr.findmalek.engineer/docs/structure.md): Apps, packages and the rules between them.

- [The extension](https://docs.skiffr.findmalek.engineer/docs/extension.md): Install it, connect it, what it does on a page.

- [The dashboard](https://docs.skiffr.findmalek.engineer/docs/dashboard.md): Answers, queue and stats.

- [Gmail job emails](https://docs.skiffr.findmalek.engineer/docs/gmail.md): Turn job alerts into queued jobs.

- [Job sources](https://docs.skiffr.findmalek.engineer/docs/sources.md): Watch careers pages and feeds.

- [Deploy](https://docs.skiffr.findmalek.engineer/docs/deploy.md): Vercel, Docker or Dokploy.

- [How skiffr learns](https://docs.skiffr.findmalek.engineer/docs/learning.md): Lookup order, what is learned, what never is.

- [Privacy and data flow](https://docs.skiffr.findmalek.engineer/docs/privacy.md): Exactly what leaves your machine.

---

# Setup

URL: https://docs.skiffr.findmalek.engineer/docs/setup
Markdown: https://docs.skiffr.findmalek.engineer/docs/setup.md

> From a fresh clone to every app running locally.

You need node 24, pnpm, bun and docker.

```bash
pnpm install
cp .env.example .env
pnpm db:up
pnpm dev --filter='!extension'
```

Edit `.env` before the first start. `BETTER_AUTH_SECRET` must be at least 32 characters (`openssl rand -base64 32` gives 44), otherwise the api refuses to start. `ADMIN_PASSWORD` must be at least 10 characters, and with `ADMIN_EMAIL` or `ADMIN_PASSWORD` empty no admin is created. `DATABASE_URL` in `.env.example` already matches the local postgres from `pnpm db:up`.

`pnpm dev` runs `turbo dev`, which starts every workspace with a `dev` script: web, api, dashboard, docs and the extension (`wxt`, which opens a development browser). `pnpm dev --filter='!extension'` starts only the four apps. Run the extension on its own with `pnpm --filter extension dev`.

`pnpm db:up` starts a local postgres (`pgvector/pgvector:pg17`) from `docker/docker-compose.yml`. The api applies migrations on start and, when `SEED=demo`, fills an empty database with sample data.

The pgvector image is debian based, the old alpine based postgres image used a different libc, so the compose file mounts a new volume, `skiffr-pgvector-data`, and never reuses the old one. Never point the new image at an old alpine data directory, text indexes break silently. Remove the old dev volume (it holds the old data) with `docker volume rm docker_skiffr-pg`.

| App | Url |
| --- | --- |
| web | http://localhost:3000 |
| api | http://localhost:3001 |
| dashboard | http://localhost:3002 |
| docs | http://localhost:3003 |

Sign in to the dashboard with `ADMIN_EMAIL` and `ADMIN_PASSWORD` from `.env`. The admin is created or reset on every api start.

## Load the extension

Build it, load it unpacked, create a token on the dashboard's Extension page and paste it in the extension options. The steps, the CI build option and what the extension does on a page are in [the extension](https://docs.skiffr.findmalek.engineer/docs/extension.md).

## Working on one app

```bash
pnpm dev:web        # web and api
pnpm dev:dashboard  # dashboard and api
```

## Before you push

```bash
pnpm lint
pnpm check-types
pnpm test
pnpm build
```

---

# The extension

URL: https://docs.skiffr.findmalek.engineer/docs/extension
Markdown: https://docs.skiffr.findmalek.engineer/docs/extension.md

> Install it, connect it to your api, and what it does on a page.

The extension is a Manifest V3 Chrome extension. There is no Chrome Web Store listing and no release yet, so you build it or take a CI build, and load it unpacked. It needs Chrome 142 or a Chromium browser of the same age.

## Install

Build it from the repo:

```bash
pnpm --filter extension build
```

In `chrome://extensions` turn on developer mode, choose Load unpacked and pick `apps/extension/.output/chrome-mv3`.

Or take a CI build: every pull request uploads `extension-chrome-pr-<number>` and every push to `main` uploads `extension-chrome-latest`, from the [CI runs](https://github.com/FindMalek/skiffr/actions/workflows/ci.yml). GitHub login is required and artifacts expire. Unzip the download, extract the inner `extension-<version>-chrome.zip` into an empty folder and load that folder unpacked.

## Connect it

1. In the dashboard open **Extension** and create a token
2. In the extension options set the api url (`http://localhost:3001` locally) and paste the token
3. Press test connection

Save your profile in the dashboard first: a fill without one stops with a message.

## Use it

On an application form (Greenhouse, Lever, Ashby, Workable, Workday and other common systems, also inside iframes) a toast asks "Autofill this application?":

- **Yes** fills the form
- **No** closes the toast
- **Don't ask on this site** stops the toast on that site

`Ctrl+Shift+F` (`Cmd+Shift+F` on macOS) fills the current page without the toast. Remap it at `chrome://extensions/shortcuts`.

For each field the extension takes the first answer it has: what you filled on this very form before, then a saved answer for the same question, then a language model that maps the field to a key of your profile (needs a provider key, see [environment](https://docs.skiffr.findmalek.engineer/docs/environment.md)). Fields the model is unsure about are filled and outlined in amber. An answer from a similar question is never filled by itself, the empty field is outlined as a suggestion. When it is done the toast says how many fields were filled and how many are outlined.

It never submits a form, never clicks submit, next or apply buttons, and never touches password or hidden inputs. You review the form and press the button.

After a fill the extension records what you corrected, cleared or left as filled, when you submit, leave the page or stop editing for 5 minutes (at most 3 batches per session). Sensitive fields are never sent, and forms with more than 60 learnable fields only record the first 60. The details and limits are in [how skiffr learns](https://docs.skiffr.findmalek.engineer/docs/learning.md). What is sent where is in [privacy](https://docs.skiffr.findmalek.engineer/docs/privacy.md).

---

# Form snapshots

URL: https://docs.skiffr.findmalek.engineer/docs/snapshots
Markdown: https://docs.skiffr.findmalek.engineer/docs/snapshots.md

> Turn a real application page into a sanitized test fixture with one command.

A snapshot is a copy of one application form from a public page, stripped of everything that is not the form. It lives in `apps/e2e/pages/snapshots/<slug>/` and the e2e suite runs detection and a fill against every folder there, so a new site becomes a test case by running one command.

## Take one

```bash
pnpm snapshot https://job-boards.greenhouse.io/acme/jobs/123
pnpm snapshot https://jobs.lever.co/acme/<id>/apply --slug lever-acme
pnpm snapshot https://jobs.lever.co/acme/<id>/apply --force
pnpm snapshot https://example.com/careers/123 --click "text=Apply now"
```

The tool opens the page in headless chromium, waits for the network to go idle plus a settle delay, optionally clicks an apply button, takes the application area, sanitizes it, and writes two files:

- `index.html`: the sanitized form, one self contained page
- `meta.json`: the source host (no path), the date, the tool version, the root as a plain tag path (`body > main > div > form`, never an id or a class from the page) and the number of fields by type

| Flag | Meaning |
| --- | --- |
| `--click <selector>` | click this (any playwright selector) before taking the form, for pages that open it behind an apply button |
| `--root <selector>` | take this element. Without it the extension's own application detection picks the form or dialog, and falls back to the form or dialog with the most fields |
| `--slug <name>` | folder name, default is the host name (`jobs-lever-co`), never words from the path |
| `--force` | replace an existing folder, otherwise the tool refuses to overwrite one. The new folder is written and checked on the side first, so a failed run keeps the old one |
| `--out <dir>` | where the folders go, default `apps/e2e/pages/snapshots` |
| `--timeout <ms>` | per page load and click, default 30000 |
| `--settle <ms>` | wait after the network is idle, default 1500 |
| `--delay <ms>` | pause between pages when you pass several urls, default 2000 |
| `--allow-local` | allow a loopback or private host, for the tool's own tests only |

Then read `index.html` once, check the site's terms, and commit the folder. The tool prints this reminder every time.

## Check

```bash
pnpm snapshot --check
```

Refuses a snapshot folder that:

- holds anything but a regular `index.html` and `meta.json` (an extra file, a nested folder, a loose file next to the folders and every symlink are refused), or is not strict utf-8
- has a script, a frame, a style element, an event handler, a remote url, an email, a phone number, a hidden input with a value, a uuid, a jwt, a long hex string or an identifier that holds a long number, read with a tokenizer that knows a `>` can sit inside a quoted attribute
- is not exactly what the sanitizer would write for itself, so a hand edited page is refused
- has a `meta.json` with other keys than the five known ones, or a value of the wrong shape (the root must be a plain tag path)

An unreadable or missing snapshots folder is an error, not a pass. The same check runs in the e2e suite and in the lint job of CI.

## Respecting the site

- Public pages only. The tool refuses a start url on a loopback, private, link local, ipv6 mapped, NAT64, 6to4 or other non public address or name unless `--allow-local`. Every spelling is judged after the url parser has normalized it, and every address a name resolves to is judged too
- Every request the page makes (page load, sub resource, fetch, xhr) is made by the tool from node, not by chromium: the tool checks the url, follows redirects itself and checks every `Location` before it requests it (at most 10 hops, a loop is an error, only http and https), and only then hands the final response to the page. Chromium therefore never follows a redirect, and the page sees the url it first asked for, not the final one
- The name is resolved by node when it connects, and every address it returns must be public, so a name that changes its answer between the check and the connection (dns rebinding) is refused too. With `--allow-local` only the page's own host and port is let through, no other private address is
- Websockets are refused outright, webrtc and quic are switched off, service workers are blocked, and a response is cut at 15 MB (100 MB per page) so a page that never stops cannot fill memory
- Not covered: this makes the page load from node's tls stack, not chromium's, so a site that fingerprints clients can answer differently.
- It identifies itself as `skiffr-snapshot/<version>` with the repo link and nothing personal, and it starts from a fresh browser profile with no cookies
- It only reads: any request that is not GET or HEAD is aborted, nothing is typed into the page, and the only click is the one you ask for with `--click`. If that selector is a submit button it is on you
- It does not read robots.txt and does not crawl. One url, one load, `--delay` between several

## What the sanitizer guarantees

The output is rebuilt from the parsed page, not patched:

- no `<script>`, `<noscript>`, `<style>`, `<link>`, `<meta>`, `<base>`, `<template>`, `<object>`, `<embed>`, audio, canvas or comments
- no `<iframe>`, `<img>`, `<video>`, `<picture>` or `<svg>`: each becomes an empty `span` or `div` with `data-skiffr-placeholder`, keeping its size and its `id`, `class`, `name`, `title` and `aria-*`. Images of 2px or less (tracking pixels) are dropped
- no inline event handler, `srcdoc`, `src`, `srcset`, `nonce`, `integrity` or `ping`
- every `style` attribute is rebuilt from an allowlist of the properties the fill checks read (display, visibility, opacity, position, offsets, size, overflow, clip, clip-path, content-visibility, pointer-events), and the capture bakes those from the live page, so hidden and honeypot fields stay hidden without any stylesheet
- every `href` is `#`, a path shape on `https://example.invalid`, or kept as a short `#anchor`. Query strings, fragments, `javascript:`, `data:`, `mailto:` and `tel:` are gone. Every form `action` and `formaction` is `#`
- every hidden input has the value `x` and keeps its name. Typed or prefilled values are removed from inputs and textareas, `checked` and `selected` are reset
- emails become `user@example.invalid`, phone numbers `000-000-0000`, uuids, jwts, long hex and base64 looking words in text become `x`. A uuid, jwt, hex string or number of six digits or more inside an `id`, `name`, `class`, `for`, option `value` or an aria reference becomes `x1`, `x2` and so on, the same one everywhere it repeats, so labels and radio groups still line up. Tokens and long ids in `data-*` are dropped, as are `ng-reflect-*` and `data-*` attributes named after a user, candidate, applicant, email or phone. A link path segment after `in`, `u`, `user`, `profile`, `candidate` and similar, or starting with `@`, becomes `x`. `data-qa`, `data-testid`, `data-automation-id`, `data-field` and a few more structural ones stay. Analytics and token named `data-*` attributes are dropped
- the output is deterministic: sorted attributes, normalized whitespace, one element per line. Sanitizing it again gives the same text for what a browser serializes (malformed table markup is the known exception)

Before it writes anything the tool loads the result in chromium with the network off and refuses it if the page makes a request or logs a console error, and refuses it if the sanitizer changed the number of fields, and runs the check above on the written folder. A page that never finishes is abandoned after a deadline of three times `--timeout` plus the settle time.

## What it does not guarantee

- Names inside identifiers (`id="user-jane-smith"`, `name="jane.smith"`, `class="jane-smith"`), numbers of five digits or fewer in an identifier (`candidate-12345`), a greeting like "Welcome, Jane Smith", ipv4 addresses and card numbers in text stay. Read the file
- Visible text is kept, apart from emails, urls and long token looking strings. A name or an address written in a label or a job description stays, and so does a name in `alt`, `title` or `aria-label`, or an `@handle`. `--check` passing does not mean there is no personal data: read the file
- A placeholder that is a two or three word capitalized name becomes `Jane Doe`, other personal looking placeholders are not detected
- Shadow DOM content and cross origin frames are not captured, and a frame becomes an empty placeholder
- Layout that comes from stylesheets is gone: the page is unstyled apart from the baked properties. Hiding done with a transform is not baked
- The ats adapters match on the host, so a snapshot served from the fixture server is detected by the generic rules, not the adapter of the site it came from
- A page that needs a login, a captcha or a bot challenge cannot be taken
- Copying a form is not permission to publish it. Check the site's terms before committing a snapshot

---

# The dashboard

URL: https://docs.skiffr.findmalek.engineer/docs/dashboard
Markdown: https://docs.skiffr.findmalek.engineer/docs/dashboard.md

> Profile, answers, queue and stats.

Sign in with `ADMIN_EMAIL` and `ADMIN_PASSWORD` from your `.env`. The sidebar has these pages.

| Page | What it does |
| --- | --- |
| Overview | where you are |
| Queue | jobs you want to apply to |
| Stats | what you applied to and what came back |
| Notes | a notes board |
| Answers | your answer bank |
| Extension | create and revoke extension tokens |
| Gmail | import job alert emails, see [Gmail job emails](https://docs.skiffr.findmalek.engineer/docs/gmail.md) |
| Sources | watch careers pages and feeds, see [Job sources](https://docs.skiffr.findmalek.engineer/docs/sources.md) |
| Settings | your profile and account |
| Users | admins only: manage the accounts on this server |

## Answers

The answer bank holds what skiffr fills for a question. Add, edit and delete answers, and see how often each was used and corrected. The suggestions panel proposes which learned answers to keep or drop, see [how skiffr learns](https://docs.skiffr.findmalek.engineer/docs/learning.md). Nothing is changed without you resolving it.

## Queue

Paste a job link, with an optional title and company, or let [Gmail](https://docs.skiffr.findmalek.engineer/docs/gmail.md) and [Sources](https://docs.skiffr.findmalek.engineer/docs/sources.md) fill it. Filter by status (queued, applied, skipped) and source, search by company or role, and use **Open next** to go through the queue in order. Mark a job applied or skipped, or restore it to the queue. The same posting is queued once, whatever way it arrived. You always press submit yourself.

## Stats

Applications per day and week, the queue funnel, replies by the furthest stage reached, breakdowns by source, ATS, match score and role, time to apply, and an autofill section: fields skiffr filled and whether you left, corrected or cleared them. Pick a range at the top. Percentages only show from 5 applications or filled fields, before that they would be noise. The autofill section counts the fields recorded after a skiffr fill, so it fills up as you use the extension. Fields skiffr did not touch are not counted.

---

# Environment

URL: https://docs.skiffr.findmalek.engineer/docs/environment
Markdown: https://docs.skiffr.findmalek.engineer/docs/environment.md

> One root .env feeds every app.

There is one `.env` at the repo root. Every app loads it, and `packages/env` validates it with zod, so a bad value fails at start with a clear message. `.env.example` lists every key with its default, `.env` itself is git-ignored.

## Urls

| Key | What it is |
| --- | --- |
| `API_URL` | how the Next servers reach the api, an internal address on docker |
| `API_PUBLIC_URL` | the api url the browser can reach |
| `WEB_URL` | the landing page |
| `DASHBOARD_URL` | the dashboard |
| `DOCS_URL` | this site. Read by `apps/docs` and also by `apps/web`, which links to it. Not part of the `packages/env` schema. Set it in production: without it the landing page links to the docs files in the repo on GitHub |

## Database and auth

| Key | What it is |
| --- | --- |
| `DATABASE_URL` | postgres connection string |
| `POSTGRES_PORT` | host port of the local docker postgres |
| `SEED` | `demo` fills an empty database with sample data, `none` never seeds |
| `BETTER_AUTH_SECRET` | at least 32 characters, no default: `openssl rand -base64 32`. The api does not start without it |
| `ADMIN_EMAIL`, `ADMIN_PASSWORD` | the first admin, created or reset on every api start |
| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | optional github sign-in |

## Models and extension

| Key | What it is |
| --- | --- |
| `AI_MODEL` | `provider:model`, default `groq:openai/gpt-oss-120b`. Providers: `groq`, `openai`, `anthropic` |
| `GROQ_API_KEY` | needed for the default model. Without any matching key the ai endpoints answer "No AI provider key is configured" and the rest keeps working |
| `OPENAI_API_KEY` | optional. Embeddings (`text-embedding-3-small`) for similar-question suggestions, see [how skiffr learns](https://docs.skiffr.findmalek.engineer/docs/learning.md) |
| `ANTHROPIC_API_KEY` | only if `AI_MODEL` points at an `anthropic:` model |
| `AI_DAILY_CALLS` | model requests one user may make per UTC day, default `600`. Chat and embedding requests both count. `0` means no limit. Counted in the database, so it holds across restarts and replicas. Digits only, at most `2147483647` |
| `AI_DAILY_TOKENS` | input plus output tokens one user may spend per UTC day, default `1000000`. `0` means no limit. Checked before each call and added after it, so a few calls in flight at the limit can overshoot it slightly |
| `AI_GLOBAL_DAILY_CALLS` | model requests the whole server may make per UTC day, all users together, default `0` (no limit). Set it on a public instance: it caps the spend of many free accounts together |
| `CLIENT_IP_HEADER`, `TRUSTED_PROXY_COUNT` | where the api reads the client address for the sign-in and sign-up limits. Defaults `x-forwarded-for` and `1`: the api sits behind one proxy that appends the address it saw (Traefik on Dokploy does). Use `0` when the api is reached directly, so the header is ignored and the connection's address is used, or the number of proxies when there are more |
| `EXTENSION_ORIGINS` | optional, comma separated `chrome-extension://<id>` origins allowed to call the api. Unset allows any extension holding a valid token |

Error reports, logs, metrics, model call traces and page analytics (`GLITCHTIP_DSN`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `UMAMI_URL`, `UMAMI_WEBSITE_ID`, `AI_TRACE_CAPTURE_CONTENT`) are optional and described in [Observability](https://docs.skiffr.findmalek.engineer/docs/observability.md).

Gmail job emails (`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `GMAIL_ENCRYPTION_KEY` and friends) are optional and described in [Gmail job emails](https://docs.skiffr.findmalek.engineer/docs/gmail.md).

Tailoring your CV through Reactive Resume (`CV_ENCRYPTION_KEY`) is optional and described in [CV tailoring](https://docs.skiffr.findmalek.engineer/docs/cv-tailoring.md).

Watching careers pages and feeds (`WATCH_SCHEDULER`, `WATCH_REFRESH_MINUTES`) needs no keys and is described in [Job sources](https://docs.skiffr.findmalek.engineer/docs/sources.md).

Every signed-in call is also rate limited per user in the api's memory (reads, writes, writes that call the embedding provider, model calls, uploads and anything that fetches the network each have their own bucket). With several replicas each one counts on its own, so the daily budget above is the real cost control. Sign-in and sign-up are limited per client address by better-auth in production, counted in the database (old rows are pruned hourly). They are not limited per account, so one email tried from many addresses is not slowed. Requests to made-up `/auth/*` paths each write a row until it is pruned: cap them at the proxy if that matters to you.

What each provider receives is listed in [privacy and data flow](https://docs.skiffr.findmalek.engineer/docs/privacy.md).

Keys for modules you left out of the project are not in `.env.example`. Adding a key means adding it to the zod schema in `packages/env` first.

---

# Structure

URL: https://docs.skiffr.findmalek.engineer/docs/structure
Markdown: https://docs.skiffr.findmalek.engineer/docs/structure.md

> Apps, packages and the rules between them.

```text
skiffr/
├─ apps/
│  ├─ web/          landing page, next
│  ├─ dashboard/    profile, answers, queue, stats, next
│  ├─ api/          orpc on bun
│  ├─ extension/    chrome extension, wxt and react
│  ├─ e2e/          playwright suite for the extension
│  └─ docs/         this site, fumadocs on next
├─ packages/
│  ├─ ui/           shadcn components and theme tokens
│  ├─ common/       shared zod schemas, constants and utils
│  ├─ orpc/         procedures and clients, built on common
│  ├─ db/           drizzle schema, migrations, seed scenario
│  ├─ ai/           field mapping and answer drafts, vercel ai sdk
│  ├─ auth/         better-auth setup
│  ├─ env/          zod-validated env
│  ├─ storage/      s3 compatible storage
│  └─ config/       shared tsconfig
├─ docker/          local postgres compose file
└─ turbo.json
```

## Rules

- `apps/api` is the only app that touches the database, auth and providers. `web`, `dashboard` and the extension call it through `@skiffr/orpc`, so secrets and data access live in one place
- anything used by more than one app or package goes in `@skiffr/common`: schemas and their types, constants, small utils. Don't redeclare a type in an app when one exists there
- the theme lives in `packages/ui/src/styles/theme.css`, use its tokens instead of raw colors
- the database schema is in `packages/db/src/schema`, change it and run `pnpm db:generate` to get a migration, never write one by hand

## Adding an endpoint

1. put the input and output schemas in `packages/common/src/schemas`
2. add the procedure in `packages/orpc/src/routers`
3. call it from an app with `orpc.<router>.<procedure>` in client components or `call((api) => ...)` on the server

---

# Scripts

URL: https://docs.skiffr.findmalek.engineer/docs/scripts
Markdown: https://docs.skiffr.findmalek.engineer/docs/scripts.md

> Every command in the root package.json.

| Command | What it does |
| --- | --- |
| `pnpm dev` | all apps and the extension dev server |
| `pnpm dev:web` | web and api |
| `pnpm dev:dashboard` | dashboard and api |
| `pnpm build` | build everything with turbo |
| `pnpm check` | biome format and fix |
| `pnpm lint` | biome and oxlint, no fixes |
| `pnpm check-types` | typescript across the repo |
| `pnpm test` | tests in every package |
| `pnpm e2e` | build the extension and run the playwright suite in `apps/e2e` |
| `pnpm snapshot <url>` | turn a public application page into a sanitized fixture, see [form snapshots](https://docs.skiffr.findmalek.engineer/docs/snapshots.md) |
| `pnpm zip` | zip the extension |
| `pnpm db:up` / `db:down` | local postgres |
| `pnpm db:generate` | write a migration from the schema |
| `pnpm db:migrate` | apply migrations |
| `pnpm db:seed` | seed the demo data |
| `pnpm db:studio` | browse the database |
| `pnpm ui:add <component>` | add a shadcn component to `packages/ui` |

Run a single app with turbo, for example `pnpm turbo dev -F docs`.

---

# Deploy

URL: https://docs.skiffr.findmalek.engineer/docs/deploy
Markdown: https://docs.skiffr.findmalek.engineer/docs/deploy.md

> Ship the apps on Vercel or your own server.

Skiffr deploys as the api, up to four Next apps, and a postgres database. All of them read the same env keys, see [environment](https://docs.skiffr.findmalek.engineer/docs/environment.md).

## Vercel

Deploy `web`, `dashboard` and `docs` as separate Vercel projects from the same repo.

1. import the repo and set the root directory to `apps/web`, then repeat for `apps/dashboard` and `apps/docs`
2. add the env keys to each project
3. host the `api` where bun or docker runs, and point `API_URL` and `API_PUBLIC_URL` at it

## Docker

Every app has a `Dockerfile` in `apps/<app>/`. The build context is the repo root and turbo prunes the workspace to what the app needs:

```bash
docker build -f apps/web/Dockerfile -t skiffr-web .
docker build -f apps/dashboard/Dockerfile -t skiffr-dashboard .
docker build -f apps/api/Dockerfile -t skiffr-api .
docker build -f apps/docs/Dockerfile -t skiffr-docs .
```

Next apps are built with `output: "standalone"` and ship a healthcheck. Pass the env at run time.

## Dokploy

Create a project with a postgres database on the docker image `pgvector/pgvector:pg17` (answer embeddings need the `vector` extension), add one application per app with build type Dockerfile, path `apps/<app>/Dockerfile` and `.` as the context, set the env keys, and attach your domains. Use the api service's internal address for `API_URL`.

Do not swap the image of an existing database in place. The pgvector image uses a different libc than an alpine based postgres image, so text btree indexes silently break on the old data. Create a new postgres service with its own volume on `pgvector/pgvector:pg17` and restore with `pg_dump` / `pg_restore`, or at least run `REINDEX DATABASE` after any libc change.

`vector` is not a trusted extension, so `CREATE EXTENSION vector` needs a superuser. If the app's database user is not one, run it once as superuser, the migration's `IF NOT EXISTS` is then a no-op.

### Client address behind Traefik

The sign-in limits are per client address. Traefik replaces any `X-Forwarded-For` a client sends with the address it saw (unless you set `forwardedHeaders.trustedIPs` or `insecure` on the entrypoint, which you should not), so the api gets one value and the default `TRUSTED_PROXY_COUNT=1` is right. The dashboard passes the header on untouched. If a proxy of your own sits in front of Traefik and appends to the header, raise the count by one for each. If the api is reachable without any proxy, set `TRUSTED_PROXY_COUNT=0`, or a client could pick its own address. A request with no usable address shares one looser bucket and the api logs a warning once: check that with `select key from rate_limit` after a few sign-ins, you should see real addresses and not `192.0.2.1`.

## Self-hosting with GitHub Actions

`.github/workflows/deploy.yml` builds the four images on every green push to `main`, pushes them to `ghcr.io/<owner>/skiffr-<app>` (tags `main` and `sha-<commit>`), redeploys the Dokploy applications and then checks `/health` on the api and the other three sites. The api migrates the database when it starts. Nothing runs until the repo variable `DEPLOY_ENABLED` is `true`.

### One-time setup

1. point four DNS records at your server (a CNAME to its public name or an A record): the base domain for the landing page, and `dashboard.`, `api.` and `docs.` under it. Traefik issues the certificates through Let's Encrypt, so ports 80 and 443 must reach Dokploy
2. create a Dokploy API key (Settings, Profile, API keys)
3. run the bootstrap, first without `--apply` to read the plan:

```bash
DOKPLOY_URL=https://dokploy.example.com DOKPLOY_TOKEN=... \
  node scripts/dokploy-bootstrap.mjs --domain skiffr.example.com --env-file .env.production
# looks right? add --apply
```

It creates the `skiffr` project, a postgres on `pgvector/pgvector:pg17` (its user is the superuser the `vector` extension needs), the `skiffr-api`, `skiffr-web`, `skiffr-dashboard` and `skiffr-docs` applications, their domains and their env. It is safe to run again: existing things are kept and an env key that is already set in Dokploy is never overwritten. `BETTER_AUTH_SECRET`, the database password and, when `ADMIN_EMAIL` is given without a password, `ADMIN_PASSWORD` are generated and live in Dokploy only. The script prints key names, never values.

`--env-file` is optional and only these keys are read from it: `ADMIN_EMAIL`, `ADMIN_PASSWORD`, `EXTENSION_ORIGINS`, `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `GITHUB_TOKEN`, the `S3_*` keys, the three Gmail keys, `AI_MODEL`, `GROQ_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and the [observability](https://docs.skiffr.findmalek.engineer/docs/observability.md) keys (`GLITCHTIP_DSN`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `AI_TRACE_CAPTURE_CONTENT`, `UMAMI_URL`, and per app `UMAMI_<APP>_WEBSITE_ID`, `GLITCHTIP_WEB_DSN`, `GLITCHTIP_DASHBOARD_DSN`). Anything left out stays unset and the api still boots, see [environment](https://docs.skiffr.findmalek.engineer/docs/environment.md).

4. set the GitHub repo settings below, then run the `deploy` workflow once from the Actions tab

| Where | Name | Value |
| --- | --- | --- |
| variable | `DEPLOY_ENABLED` | `true` |
| variable | `PRODUCTION_DOMAIN` | the base domain, for example `skiffr.example.com` |
| variable | `DOKPLOY_URL` | the public url of Dokploy |
| secret | `DOKPLOY_TOKEN` | the Dokploy API key |
| variable, optional | `TURBO_API`, `TURBO_TEAM` | a turbo remote cache for the image builds |
| secret, optional | `TURBO_TOKEN`, `GHCR_READ_TOKEN` | the cache token, and a `read:packages` token if the ghcr packages are private |

`DOKPLOY_URL`, `DOKPLOY_TOKEN` are the same settings the PR previews use.

Back up the database from Dokploy (Backups tab of the postgres service) to an S3 destination. The `backup` workflow only works against a database that is reachable from GitHub.

### Rollback

A deploy that dies in its first seconds keeps the old container (Dokploy services start first and roll back on failure). To go back to an older version set the previous `sha-` tag on the application in Dokploy, or run the workflow again on an older commit. A bad migration is not rolled back.

---

# Previews

URL: https://docs.skiffr.findmalek.engineer/docs/previews
Markdown: https://docs.skiffr.findmalek.engineer/docs/previews.md

> A running copy of every pull request, with its own database and bucket.

Every pull request from this repository gets a preview of all apps on the self-hosted Dokploy: the landing page, the dashboard, the api and the docs (and the e2e playground once it has a Dockerfile). One sticky comment on the pull request lists the links, a test login and the extension build. Closing or merging the pull request deletes all of it.

Nothing is created until the repo variable `PREVIEW_ENABLED` is `true`. Cleanup and the sweep do not check it, so turning previews off still removes what exists, and they run against the real Dokploy as soon as the secrets are set, even before previews are enabled. After merging, run the `preview-sweep` workflow once with `dry_run` and read what it would remove before you enable previews. Pull requests from forks and from dependabot get no preview: they cannot read the secrets.

## What a push does

1. **plan** asks turbo which packages the pull request changes (`turbo ls --affected`, dependents included). An app is built when it is in that list. A change to a shared package such as `@skiffr/orpc` or `@skiffr/db` rebuilds every app that uses it. If turbo fails or its output cannot be read, every app is built.
2. **build** builds the changed apps on GitHub runners with docker buildx and pushes `ghcr.io/findmalek/skiffr-<app>:pr-<number>-<short sha>`. It uses the same build args as the production build, so the layers and the turbo remote cache (`TURBO_API`, `TURBO_TEAM`, `TURBO_TOKEN`) that `main` already warmed are reused.
3. **dokploy** creates or updates the preview in the Dokploy project `skiffr-previews`: a bucket, a postgres, then the apps, the api first. An app that was not built runs the production image `ghcr.io/findmalek/skiffr-<app>:main`, wired to the preview's own env. The images are env agnostic: the Next apps read `API_URL` per request, so the production image works behind a preview api.
4. it waits for the deploys, checks `/health` of the api (the database answers and `env` is `pr-<number>`) and every other app, then edits the sticky comment and the GitHub deployment `preview-pr-<number>`.

A new push cancels the running one. An app that is behind `main` is not rebuilt: a preview mixes the pull request's changed apps with the latest production images of the rest.

## What a preview owns

| What | Name |
| --- | --- |
| apps | `skiffr-<app>-pr-<number>` at `https://pr-<number>-<app>.<PREVIEW_DOMAIN>` |
| database | a Dokploy postgres `skiffr-db-pr-<number>` on `pgvector/pgvector:pg17`, its own user and password, its own volume |
| bucket | `skiffr-pr-<number>` on the S3 api (the api also prefixes keys with `pr-<number>/`) |
| env | its own `BETTER_AUTH_SECRET`, `ADMIN_PASSWORD`, `DATABASE_URL`, urls, `DEPLOY_ENV=pr-<number>` |

The api migrates the database when it starts and creates the admin from `ADMIN_EMAIL` and `ADMIN_PASSWORD`. A dedicated postgres per preview needs nothing but the Dokploy api to create and delete, and removing it frees the data. A shared postgres server with a database per preview would be lighter, but creating and dropping databases needs a connection from the runner, and the server is not reachable from GitHub.

Nothing from production is shared. Previews get no model key, no Google client and no GitHub OAuth client, so the AI, Gmail import and GitHub sign in stay off. The job source and Gmail schedulers are off. The optional secret `PREVIEW_GROQ_API_KEY` (a key with its own small budget, never the production key) turns the model on with `AI_DAILY_CALLS=20` and `AI_GLOBAL_DAILY_CALLS=200`.

`DEPLOY_ENV=pr-<number>` makes the web and docs apps answer `noindex`. `EXTENSION_ORIGINS` is not set on previews: an unpacked extension has no stable id, so any extension origin may call the preview api with a token.

## The seeder

The preview api seeds its empty database on start. It sets `SEED=preview` when `packages/env/src/api.ts` accepts that value, and `SEED=demo` until then. The contract for the seeder is: `SEED=preview` seeds a realistic, deterministic dataset into an empty database only, never touches a database that already has data, and runs inside the api start (after the migrations and `ensureAdmin`). The test login in the comment is the env admin. Any extra seeded accounts belong in the seeder's own documentation.

## The extension

The comment links the CI run that holds the artifact `extension-chrome-pr-<number>` (built by the `extension` job of every pull request). Unzip it twice, load the folder unpacked, set the api url in the options to the preview api (`https://pr-<number>-api.<PREVIEW_DOMAIN>`), then create a token in the preview dashboard under Extension and paste it. The extension has no build time default for the api url.

## Cleanup

- `preview-cleanup` runs when a pull request is closed or merged. It deletes the apps (their domains go with them), the postgres and its volume, the bucket with its objects, the `pr-<number>-*` image tags on ghcr (best effort, a failure only leaves registry clutter), and marks the GitHub deployments inactive. It is safe to run twice and a cleanup in progress is never cancelled. A bucket that holds an object key with a dot segment (`..` or `.`) is refused and stays, which turns the nightly sweep red until someone empties and deletes it by hand. A failed `up` leaves its apps and postgres in place, they count toward `PREVIEW_MAX` until the pull request closes or the idle limit hits.
- `preview-sweep` runs daily, or by hand with `dry_run` to only list. It removes previews of closed pull requests the cleanup missed, previews idle for more than `PREVIEW_TTL_DAYS` (default 7) even when the pull request is open (a push brings it back), and the leftover postgres volumes and buckets of those pull requests. A github answer other than closed or 404 (an outage, a rate limit) stops the sweep with an error instead of deleting anything. Dokploy's `postgres.remove` leaves the data volume behind, so both paths remove it through `dockerVolume.removeVolume`.
- at most `PREVIEW_MAX` previews (default 6) run at once. A new one over the limit is skipped, the comment says so, and it starts on the next push once there is room.

Image layers of old previews stay in the box's docker cache: turn on Dokploy's daily docker cleanup in Settings, Server.

Both scripts take `--dry-run`:

```bash
DOKPLOY_URL=... DOKPLOY_TOKEN=... GITHUB_TOKEN=... GITHUB_REPOSITORY=FindMalek/skiffr \
  node .github/scripts/preview.mjs sweep --dry-run
```

## One-time setup

DNS, one record: `*.preview.skiffr` CNAME to `home.findmalek.engineer`, TTL 60. Every preview host is one label under it (`pr-12-web.preview.skiffr.findmalek.engineer`), so a single wildcard certificate covers all of them. Without it each host orders its own Let's Encrypt certificate, and the weekly limit of 50 certificates per domain is reached after a few pull requests.

Certificate, once, on the Dokploy box: put this in `/etc/dokploy/traefik/dynamic/preview-skiffr-wildcard.yml`. Traefik orders the wildcard certificate with the DNS challenge resolver `vercel` and every preview router reuses it.

```yaml
http:
  routers:
    preview-skiffr-wildcard-cert:
      rule: Host(`preview.skiffr.findmalek.engineer`)
      entryPoints: [websecure]
      service: noop@internal
      tls:
        certResolver: vercel
        domains:
          - main: "*.preview.skiffr.findmalek.engineer"
```

Preview domains are created with `certificateType: custom` and `customCertResolver: vercel` (the variable `PREVIEW_CERT_RESOLVER`; `letsencrypt` uses the HTTP challenge and one certificate per host instead).

S3, once: create a key that may create buckets and nothing else, so the runner needs no admin access. On Garage: `garage key create skiffr-preview-key`, then `garage key allow --create-bucket skiffr-preview-key`. A key owns the buckets it creates and can empty and delete them.

| Where | Name | Value |
| --- | --- | --- |
| variable | `PREVIEW_ENABLED` | `true` |
| variable | `PREVIEW_DOMAIN` | `preview.skiffr.findmalek.engineer` |
| variable | `DOKPLOY_URL`, `PRODUCTION_DOMAIN` | the same as for the production deploy |
| secret | `DOKPLOY_TOKEN` | the same Dokploy API key |
| variable, optional | `PREVIEW_S3_ENDPOINT`, `PREVIEW_S3_REGION` | the S3 api (`https://s3.findmalek.engineer`) and its region (`garage` unless configured). Without them previews have no uploads |
| secret, optional | `PREVIEW_S3_ACCESS_KEY_ID`, `PREVIEW_S3_SECRET_ACCESS_KEY` | the bucket creating key |
| variable, optional | `PREVIEW_MAX`, `PREVIEW_TTL_DAYS`, `PREVIEW_CERT_RESOLVER` | 6, 7 and `vercel` |
| variable, optional | `TURBO_API`, `TURBO_TEAM` | the turbo remote cache for the builds |
| secret, optional | `TURBO_TOKEN`, `GHCR_READ_TOKEN`, `PREVIEW_GROQ_API_KEY` | the cache token, a `read:packages` token (ghcr packages are private unless made public), and a model key with its own budget |

Never log Dokploy into ghcr with a workflow token: it expires with the run and every later pull on the box fails. `GHCR_READ_TOKEN` is the only registry login the scripts send.

## Limits

- previews are public: anyone with a link can sign in with the test login. Only same-repo pull requests get one, the data is fake and the model and mail are off, but do not put anything real in a preview.
- one S3 key owns all preview buckets, and a bucket has no quota. The daily sweep and the idle limit bound the space. There is no isolation between previews: the key sits in every preview api env, so pull request code running in one preview can read, write and delete the buckets of all the others.
- the previews are public on the internet with a published test login, and each one runs five containers with no resource limits.
- the preview of an app that was not rebuilt runs the latest `main` image, which can be newer than the pull request's base.
- the `web` and `docs` builds bake the production site url into their metadata. The previews tell search engines not to index.

## Threat model

Under `pull_request` the workflow file comes from the merge ref, so anyone who can push a branch to this repository can change the workflow or the scripts and read `DOKPLOY_TOKEN`, `PREVIEW_S3_*` and `GHCR_READ_TOKEN`, whatever the checkout ref is. Checking out `main` for the scripts does not change that, and `pull_request_target` would be worse. Forks and dependabot are skipped, and nothing a branch name or title carries reaches a shell.

- `DOKPLOY_TOKEN` is a full admin key, the same power as production. Whoever can push a branch can delete `skiffr-db`. If Dokploy lets you create a key scoped to the `skiffr-previews` project, use that one. Otherwise keep write access to the repository tight.
- all previews share one S3 key (see the limits) and are public.

---

# How skiffr learns

URL: https://docs.skiffr.findmalek.engineer/docs/learning
Markdown: https://docs.skiffr.findmalek.engineer/docs/learning.md

> Lookup order, what is learned, what never is, and how skiffr advises you.

> **Note**
>
>
> The correction log, the lookup and the suggestions are on `main` ([#49](https://github.com/FindMalek/skiffr/pull/49)) and covered by tests on real Postgres. The extension calls the lookup when it fills, and records your edits after a fill ([#67](https://github.com/FindMalek/skiffr/pull/67)), so what you correct is learned. The limits are at the end of this page.

skiffr fills a form, you fix what is wrong, and the fixes become answers. The target is fewer corrections per application over time.

## Lookup order

For every field the api tries, in this order, and stops at the first hit:

1. **Exact fingerprint.** The same normalized label, the same control type and the same set of options (a hash of the option texts) as an answer you already have.
2. **Normalized label.** The same question with different wording around it: case, punctuation and spacing are ignored.
3. **Embedding similarity.** Questions that mean the same thing. This needs `OPENAI_API_KEY`, and it only ever produces a suggestion.
4. **None.** The extension falls back to the language model, which maps the field to a profile key. Without a provider key the field is left empty.

Rules that apply to every candidate:

- the control has to be the same kind (a text answer is never put in a select)
- when the field has options, the answer has to be one of them, and the option text is what gets filled
- an answer you rejected is never returned
- a similarity match needs a cosine score of at least 0.92 and a clear lead of 0.05 over the runner-up. It comes back with `autofill: false`, so the extension shows it as a suggestion and does not fill it by itself. The threshold is a floor until there is real data to tune it

An exact or label match is filled automatically, except long values (over 300 characters) and answers you cleared three times in a row.

## What is learned

Every filled field is compared with its final value when you move on.

- **Accepted:** the answer's use count goes up.
- **Corrected:** your final value becomes the answer for that label, and its correction count goes up.
- **Cleared:** counted as a correction. An empty value is never learned, and three clears in a row stop automatic filling of that answer.

Each event is stored with the application it belongs to, which gives corrections per field for every application. The sequence over your applications is the metric to watch. Repeated sends of the same batch change nothing, so a retry never double counts.

## What is never learned

- password, one-time code and card fields, and anything the page marks with an autocomplete token such as `cc-*`, `one-time-code`, `new-password`, `current-password` or `bday*`
- labels for secrets, card and bank data, government and tax ids, birth dates, and equal opportunity categories (gender, ethnicity, race, disability, religion, veteran status, orientation, marital status), in English, French, German, Spanish and Arabic
- control kinds outside an allowlist, and fields with no declared type
- values over 300 characters: the correction is logged but not learned, and if you correct a field to a value over 300 characters, the old learned answer for that label is deleted
- values that look like a card number (13 to 19 digits that pass the Luhn check), a valid IBAN or a US social security number (`123-45-6789`): never stored or filled, whatever the field is called. This is a backstop for labels the lists above do not think of
- anything beyond 2000 answers per user

Embeddings are computed from the normalized question, never from the answer.

## Suggestions

skiffr tells you which learned answers to keep or drop:

| Suggestion | When |
| --- | --- |
| keep | corrected at least twice in 90 days and every correction ended on the current value |
| flip-flop | corrected at least three times, with more than one distinct value, and the last three are not identical |
| cleared | cleared three times in a row |
| stale | untouched for 180 days |

You resolve each one. Nothing is deleted or rewritten without that.

## Retention

Each filled field is logged as an event: raw label, the value that was filled and the value you left (up to 2000 characters each), per user. Events older than 90 days are deleted, but only when the extension records new events or asks for suggestions, and at most 500 per call. An account that goes quiet keeps its old events until the next call. Events are deleted with the user (cascade), see [privacy](https://docs.skiffr.findmalek.engineer/docs/privacy.md).

## What the extension records

After a skiffr fill the extension watches the form. It sends one batch of events (corrected, cleared, left as filled) to your api through the background worker:

- when you submit the form, when you leave the page or the tab goes to the background, or after 5 minutes without an edit
- at most 3 batches per session, a later one only carries what changed
- sensitive fields and values are filtered in the content script and again in the worker, so they are never sent

Limits today:

- only after a skiffr fill, and fields that already had a value at fill time are not recorded
- forms with more than 60 learnable fields only record the first 60
- a hidden tab cannot send, so closing a background tab or quitting the browser loses that batch
- the session ends after delivery of the last batch, later edits are not recorded
- fields in cross-origin iframes are not recorded
- some harmless labels are blocked because the filter fails closed, for example a label that is just `Code`

---

# Gmail job emails

URL: https://docs.skiffr.findmalek.engineer/docs/gmail
Markdown: https://docs.skiffr.findmalek.engineer/docs/gmail.md

> Turn LinkedIn, Indeed and Glassdoor job alerts into queued jobs.

skiffr can read the job alert emails in your Gmail inbox and put the jobs in your queue. It is off until the person running skiffr creates a Google OAuth client and sets three variables. Each user then connects their own mailbox from the dashboard under **Gmail**.

Gmail import is verified against a local stand-in for Google's API in the tests. It has not been run against real Google yet, so expect small fixes the first time you connect.

## What it does

Every 15 minutes (and when you press **Sync now**) skiffr looks for unread inbox mail of the last 14 days from the senders you watch. For each email it finds the jobs (title, company, link), adds new ones to your queue with the source `gmail:linkedin`, `gmail:indeed` and so on, and only then tidies the email: marks it read, takes it out of the inbox and adds the `skiffr/jobs` label.

- An email with no jobs in it is left exactly where it is.
- Emails are never deleted, trashed or sent.
- The same posting is queued once: by the same id the dashboard and the extension use (`linkedin:<id>`, `indeed:<jk>`, `greenhouse:...`, otherwise the link without tracking parameters), so a job found in an email and the same job added by hand are one row. A link that is only a click tracker is matched by title and company.
- Links in emails are never opened by the server. A click-tracking link whose posting can't be read from the link itself is stored as it came and shown with a "Tracking link" badge.
- Default senders are LinkedIn, Indeed, Glassdoor, Wellfound and ZipRecruiter alert addresses. They are a best-effort starting point: edit them if your alerts come from another address.

The layouts of the alert emails are not documented by the boards and change. The parsers are written from approximations of them, so an email they can't read gives no jobs and stays in your inbox. Report the sender and board in an issue, without the email.

## 1. Create the Google OAuth client

1. In the [Google Cloud console](https://console.cloud.google.com/) create a project and enable the **Gmail API**.
2. Open **Google Auth Platform** (formerly OAuth consent screen). Choose the **External** user type, fill in the app name and your email.
3. Under **Data access** add the scope `https://www.googleapis.com/auth/gmail.modify`. It is the smallest scope that can read mail and change labels. Google marks it **restricted**.
4. Under **Clients** create a client of type **Web application**. Add this authorized redirect URI, exactly:

   ```text
   <DASHBOARD_URL>/api/gmail/callback
   ```

   For example `https://app.example.com/api/gmail/callback`. The callback goes through the dashboard because that is where the session cookie lives. To use another address set `GOOGLE_REDIRECT_URI`, it must match the client.
5. Copy the client id and secret into the environment (below).

### Testing mode expires the connection after 7 days

A new consent screen starts in **Testing**. Google expires refresh tokens of apps in testing after 7 days, and skiffr then shows "Needs reconnecting" every week. For your own use, press **Publish app** to move it to production.

Without Google's verification this works with a warning screen ("Google hasn't verified this app", choose Advanced, then continue) and a limit of 100 users for the life of the client. Because `gmail.modify` is a restricted scope, a public app serving other people has to pass Google's verification and an annual security assessment. For one person or a small team on a self-hosted skiffr that is usually not worth it: stay unverified, and everyone connects through the warning screen.

## 2. Environment

| Key | What it is |
| --- | --- |
| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | the OAuth client from step 1 |
| `GMAIL_ENCRYPTION_KEY` | 32 random bytes, base64: `openssl rand -base64 32`. Seals the stored refresh tokens. If you lose or change it, everyone has to connect again |
| `GOOGLE_REDIRECT_URI` | optional, defaults to `<DASHBOARD_URL>/api/gmail/callback` |
| `GMAIL_SYNC_INTERVAL_MINUTES` | optional, default 15. The real interval varies by 20% so replicas and restarts don't line up |
| `GMAIL_SCHEDULER` | `on` (default) or `off`, see below |

Set all three of the first group or none: a half set fails at start. Without them the Gmail page says it is not set up, `/gmail/connect` answers 404 and nothing is scheduled.

## 3. Schedule

By default the api reads mail itself. With several api replicas, one of them (chosen with a Postgres advisory lock) does it, and another takes over if it stops. The mailbox being read is also leased in the database, so a **Sync now** click and the schedule never run one mailbox at once. The advisory lock belongs to one database session, so `DATABASE_URL` must be a direct Postgres connection, not a transaction pooler such as pgbouncer in transaction mode.

To run it as a Dokploy scheduled job instead, set `GMAIL_SCHEDULER=off` on the api and add a job to the api service with the command `bun run gmail:sync` (it runs from `apps/api`, reads the same environment, does one pass over every due mailbox and exits). Run it every 15 minutes.

A run reads at most 200 listed emails and handles at most 50 new ones. A rate limit or a Google error stops that mailbox until later and the next run picks up where it stopped. If Google no longer accepts the saved access, the mailbox is marked **Needs reconnecting** and nothing retries it.

## Privacy model

- **Reads** only unread inbox emails from the watched senders. The sender is checked again on the real address, and an email is only read when Gmail's own `Authentication-Results` shows a dmarc pass for the sender's domain. No header, `dmarc=none` or a fail is skipped. This is best effort: a sender whose domain does not enforce dmarc can only be trusted as far as Gmail's check goes. Attachments are never opened.
- **Stores** per email: Gmail's message id, the board, an outcome and counts. Per job: title, company, link. Not the email body, subject or sender address. Your Gmail address and the encrypted refresh token are kept on your connection.
- **Encryption**: the refresh token is sealed with AES-256-GCM, a random IV per value and the user id as additional data, so a token copied to another row doesn't open. The key is `GMAIL_ENCRYPTION_KEY`. Tokens are never returned by the api and never logged, and neither is any email text. Access tokens live in memory for a few minutes.
- **Session only**: the Gmail calls need a signed-in browser session. An extension token can't call them.
- **Text from emails** is attacker-controlled. It is stored as plain text with control and direction characters removed, cut to 200 characters, and shown as text, never as HTML.

## Revoking

Press **Disconnect** on the Gmail page: skiffr revokes its access at Google, deletes the connection, the watched senders and its list of read emails. Jobs already queued, your emails and the `skiffr/jobs` label stay. You can also remove skiffr at [myaccount.google.com/permissions](https://myaccount.google.com/permissions), skiffr then shows "Needs reconnecting". Deleting a user deletes their connection with them.

---

# Job sources

URL: https://docs.skiffr.findmalek.engineer/docs/sources
Markdown: https://docs.skiffr.findmalek.engineer/docs/sources.md

> Watch careers pages and feeds and queue the new postings.

skiffr can watch a careers page or a feed and put new postings in your queue. You add the address under **Sources** in the dashboard, give it a name, and the api fetches it about once an hour.

## What you can watch

| Address | How it is read |
| --- | --- |
| RSS, Atom or JSON Feed | the title and link of each item |
| a Greenhouse, Lever, Ashby or Workable board | the board's public listing. Give the board address you would open in a browser (`boards.greenhouse.io/acme`, `jobs.lever.co/acme`, `jobs.ashbyhq.com/acme`, `apply.workable.com/acme`, `acme.workable.com`) and skiffr reads the vendor's public json for it |
| any other web page | schema.org `JobPosting` data in the page when there is some, otherwise the links that look like a posting: on the page's own site or a known board, with a path like `/careers/<role>` and a title that is not navigation |

A page that builds its list with JavaScript, or sits behind a login, gives nothing: skiffr reads the html the server sends and does not run scripts. Find the page's feed or its board address instead.

Postings are queued with the source `watch:<name>` (the queue shows "Watched · name") and deduped by the same id the dashboard, the extension and Gmail use, so a job you also added by hand stays one row. skiffr remembers what it queued from a source: a job you delete does not come back on the next fetch.

At most 100 new jobs are queued per fetch. A long board fills up over the next fetches. The first fetch of a source with many postings queues them all (up to that limit), so expect a burst.

Removing a source stops the fetching. Jobs it already queued stay.

## Limits

| What | Limit |
| --- | --- |
| sources per user | 20 |
| time between fetches of one source | `WATCH_REFRESH_MINUTES` (default 60, at least 15), longer after a failure (doubling, up to a day) |
| **Run now** | once a minute per source, 6 in ten minutes per user |
| fetches per user | 60 an hour |
| requests to one host | one a second |
| response | 2 MB on the wire and again after decompression, 20 seconds in total, 3 redirects |
| postings read from one page | 500 |

## Environment

| Key | What it is |
| --- | --- |
| `WATCH_SCHEDULER` | `on` (default) or `off`. Off keeps the api from fetching on a schedule. **Run now** still works |
| `WATCH_REFRESH_MINUTES` | minutes between fetches of one source, 15 to 1440, default 60 |

With several api replicas, one of them (chosen with a Postgres advisory lock, like Gmail) runs the schedule, and the source being fetched is leased in the database so a click and the schedule never fetch it at once. `DATABASE_URL` must be a direct Postgres connection, not a transaction pooler.

## Security model

The server fetches addresses that users type in, so this is the part to read.

- **Only public web pages.** The address must be `http` or `https` on port 80 or 443 and must not carry a username or password. Names such as `localhost`, `*.local`, `*.internal` and single-label hosts are refused. Address literals are read the way a browser reads them, so `2130706433`, `0x7f000001`, `0177.0.0.1` and `127.1` are all `127.0.0.1`, and refused.
- **The name is resolved by skiffr, and every answer must be public.** A name that resolves to any private, loopback, link-local (`169.254.169.254`, the cloud metadata address), carrier-grade NAT (`100.64.0.0/10`), multicast, reserved or documentation range of IPv4, or outside global unicast in IPv6 (unique local `fc00::/7`, link-local, IPv4-mapped, NAT64, 6to4, Teredo), is refused as a whole, even if another answer is public.
- **The connection goes to the address that was checked.** There is no second lookup between the check and the connect, so a name that answers differently the next time (dns rebinding) cannot send the request somewhere else.
- **Every redirect starts over.** At most 3 hops, and each target goes through the same checks, resolution included.
- **Bounded.** 2 MB on the wire and after decompression (a gzip bomb stops at the same number), a deadline for the whole fetch and an idle timeout (a slow server is cut), and only html, xml, rss, atom and json content types are accepted. Only `identity` and `gzip` encodings are asked for.
- **Nothing identifying is sent.** One fixed user agent, `skiffr-watcher/1.0`, no cookies (none are sent, kept or read), no referrer, no authorization.
- **Job links are stored, never opened.** Links found on a page must be plain `http(s)` links without credentials or internal hosts, and are only shown to you to click.
- **Page text is untrusted.** Titles and company names lose all markup, entities, control and direction characters and are cut to 200 characters. They are shown as text, never as html.
- **Parsing is bounded.** Pages are read with a streaming parser (`htmlparser2`) that builds no tree, so deep nesting costs nothing, at most 500 postings are kept, and JSON-LD blocks are capped in size, count and depth. A DOCTYPE with entities is never expanded.
- **Per-user and per-host limits** and the source cap above keep one account from using the server to hammer a site.
- **Session only.** The extension token can't call these routes.
- **Logs** carry the source id, the step and the kind of failure, never an address, a header or any page content.

What this does not cover: skiffr cannot stop a public site from serving a misleading posting, and anything reachable from the api's own network position through a public address (for example a public host that proxies into your network) is as reachable as it is to anyone. Run the api in a network where it can reach what it must and nothing more.

## Why a source shows a problem

| Code | Meaning |
| --- | --- |
| blocked | the address is not a public web page. It is retried once a day |
| dns | the name does not resolve |
| network, timeout, upstream | the site was unreachable, slow or had an error. Retried with a growing wait |
| rate_limited | the site said 429. Its `Retry-After` is honored, up to a day |
| not_found | 404 or 410 |
| too_large, content_type | the response was over 2 MB, or not a web page or feed |
| unparseable | a feed or board answered with something that is not one. A web page with no postings is not an error: it shows 0 postings |

---

# CV tailoring

URL: https://docs.skiffr.findmalek.engineer/docs/cv-tailoring
Markdown: https://docs.skiffr.findmalek.engineer/docs/cv-tailoring.md

> Tailor your Reactive Resume to a job, with a copy per application and never a new fact.

skiffr can make a per-job copy of your CV through your [Reactive Resume](https://rxresu.me). You paste the job description on a queued job, read every change and a keyword score, and confirm. skiffr then makes a **copy** of your base resume named after the company and role, applies the changes to the copy, and gives you its link and a PDF. Your base resume is never edited.

## Set up

1. The person running skiffr sets `CV_ENCRYPTION_KEY` (32 random bytes, base64: `openssl rand -base64 32`) and an AI provider key (`GROQ_API_KEY` or another, see [environment](https://docs.skiffr.findmalek.engineer/docs/environment.md)).
2. In Reactive Resume, create an API key with **read, write and delete** access (Settings, API keys).
3. In the dashboard open **CV**, enter the address of your instance (the hosted one is `https://rxresu.me`, or your own **https** address) and the key. skiffr calls the instance once to check the key before it saves anything.
4. Pick the base resume.
5. In the **Queue**, press the CV button on a job, paste the posting, and preview.

## What it may change

The AI proposes a JSON Patch (RFC 6902) and only these edits survive:

| Edit | Rule |
| --- | --- |
| headline, summary | rebuilt only from whole clauses of the existing headline and summary: reordered or dropped, never cut or reworded |
| skill keywords | reordered or dropped inside their own group. One is added only if your profile lists it under skills. Never moved to another group |
| skill groups | reordered |
| bullets of an experience entry | reordered, dropped, or rebuilt from whole clauses of that entry's own bullets. No new bullets, no new words |
| entries, skill groups, sections | hidden. Only hidden: nothing can be made visible again |

Everything else is out: names, contact details, companies, titles, dates, schools, degrees, certifications, the order of experience entries, the design.

## Never inventing facts

This is enforced in code, not only in the prompt. Every proposed edit is checked before it is shown, and again when you confirm:

- the operation must be `replace` (or `move` of a skill group) on an allowed path. Anything else is dropped
- text is extractive and whole-clause only. A clause is the part of a sentence between commas, semicolons, colons or full stops. Every clause of a new headline, summary or bullet must be a whole clause already in the allowed source, and what is stored is the source's own wording, so a symbol, a case change or an angle bracket from the model never gets in. A clause is never cut, so a "not", "no", "non-" or "assisted" can't be dropped, and a figure keeps its unit, its words and its entry. Two clauses can be joined with a comma, which can read as a fragment: you see the result in the preview
- the headline and summary can reuse only clauses of the existing headline and summary. A bullet can reuse only clauses of its own entry, so a figure, a date or a company can't move to another entry (a bullet's clauses can still be recombined within the entry)
- skills are stored as you wrote them, so a symbol, a changed case or a duplicate can't come in
- hidden entries, hidden sections, a hidden summary and custom sections are not a source of anything, and are never sent to the model
- the job posting never counts as a source
- hidden characters (zero width, direction overrides), letters that look like Latin ones from another script, and digits of other scripts are refused
- a patch has at most 40 operations and 24 kB (a longer model reply is cut down, a longer request from a client is refused), and each text has a length cap

A refused edit is dropped and counted in the dialog ("2 suggestions wrote something that is not copied from your resume"); the rest still apply. The job description is treated as untrusted text: a posting that says "add a PhD" changes nothing, because it is a source of nothing. It is also sent to the model inside an escaped data block with an instruction to ignore requests found in it.

## The keyword score

The score is plain counting. skiffr takes the 30 most repeated meaningful words of the posting (without common words, boilerplate like "team" or "experience", and words that look like instructions) and counts how many appear in the resume text a reader would see, before and after. Forms of a word match (`deploy`, `deployed`). Hidden sections and entries do not count. The matched and missing words are listed. No model is asked for a number.

Be clear about what this means. The copy is your resume reordered, trimmed and partly hidden. Reordering and cutting clauses can't add a keyword, and hiding something removes its words, so the score stays the same or goes down (hiding an old job can show as minus a few points). It goes up only when a skill listed in your profile is added. This is a per-job copy with the relevant parts first, **not an ATS booster**. A missing word is worth adding only if it is true for you, and you do that in Reactive Resume. It is a rough guide, not what any real applicant tracking system computes.

## Security

- **The key** is sealed with AES-256-GCM using `CV_ENCRYPTION_KEY`, bound to your account and to this feature, so a stored value copied to another account, or a Gmail token sealed with the same server key, does not open. It is decrypted only inside a call to your instance. It is never sent to the browser (only the last 4 characters are shown), never logged, and not reachable with an extension token.
- **The address** is called only if it is a public **https** site on port 443. Private, loopback and link-local addresses are refused at connect time and again after name resolution, redirects are not followed (so the key never travels to another host), and responses are capped at 2 MB (8 MB for a PDF).
- **The data** that reaches the AI provider: the visible text of your base resume (not hidden entries, hidden sections or custom sections), the shared parts of your profile (names, links, skills, summary; no contact details or pay) and the job description you paste.
- **Limits per user and hour**: 20 tailoring runs, 20 copies and 120 other calls to your instance, and a quarter second between one user's calls to an instance, so one account can't use up another's turn. The counts live in the api process: they reset on a restart, and each replica counts for itself.
- **Delete access** on the key is used for one thing: if a copy was made and the changes can't be applied, skiffr moves that copy to the trash again. It never touches another resume. If that fails too, the error names the copy so you can remove it.

## Limits

- Needs a Reactive Resume version with the `/api/openapi/resumes` API (copies or duplicate, patch, pdf). A resume in an older data format is refused.
- The extractive rules make rewording impossible on purpose: tailoring is reordering, dropping whole clauses, and hiding. It will not borrow a better verb, cut a clause short or merge two bullets, and a summary with a single clause can only stay or go. Joining clauses with a comma can produce an awkward fragment. That is the price of never putting a claim in front of a recruiter that you did not write.
- Only the part of the resume above is changed. The summary is rewritten as plain paragraphs (links or bold in it are lost); bullets are only rewritten when an entry's description is a plain list. A bullet that is kept unchanged keeps its formatting.
- You paste the posting: skiffr does not fetch the job page.
- The PDF limits (30 seconds without a byte, 60 in total, 8 MB) and the 2 MB JSON cap have not been tried on a real instance.
- A self-hosted instance must be reachable on a public address, on port 443 (`https://my-rr.example:8443` is refused), with a response under 2 MB (a resume with a large inline picture may exceed it). A PDF may take up to a minute to render.
- If the changes can't be applied after the copy was made, the copy is moved to the trash. Only if that also fails does a copy stay behind, and the error says which.

## Environment

| Key | What it is |
| --- | --- |
| `CV_ENCRYPTION_KEY` | 32 random bytes, base64. Seals the stored Reactive Resume keys. Unset: the feature is off. Losing it means entering the keys again |

---

# Observability

URL: https://docs.skiffr.findmalek.engineer/docs/observability
Markdown: https://docs.skiffr.findmalek.engineer/docs/observability.md

> Optional error reports, analytics, logs and model call traces, and what each one is allowed to send.

Everything here is off until its variable is set. An instance without any of it behaves as before, makes no request to a third party and has no extra dependency on the hot path. Web, docs and dashboard still load `/analytics.js` from their own origin, which is an empty comment while Umami is unset. Privacy is the promise of the product, so each sink sends from an allowlist: a field label, a form value, resume or job text, an email or a token has no key to travel under.

## What to use

| Tool | Decision | Why |
| --- | --- | --- |
| GlitchTip | adopt | Sentry compatible errors, already running. The api, web and dashboard report by error class, stack and ids |
| Umami | adopt | page views for web, docs and dashboard, no cookie, honours Do Not Track. Plus one counted api event |
| OpenObserve | adopt | one place for request logs, metrics (health, schedulers, rate limits, model budget) and model call traces over OTLP |
| Langfuse | defer | not running on the box, and self hosting is six containers (web, worker, postgres, redis, clickhouse, S3). Two structured output calls and a validator do not need prompt management yet. Model call traces are standard OTLP, so pointing them at Langfuse later is a change of endpoint when the evals of issue #41 need datasets |
| Braintrust | skip | a hosted service that would receive prompts made of personal data, and it overlaps OpenObserve plus Langfuse |
| Mastra | skip | an agent framework for orchestration skiffr does not have: it calls a model with a schema, twice |
| Sentry SDK | skip | `@sentry/bun` pulls in `@sentry/node` and its OpenTelemetry instrumentation and collects request context and breadcrumbs, to be scrubbed afterwards. The api builds the envelope itself from allowlisted fields, so there is nothing to scrub |

## What leaves the process

`packages/observability` is the only code that sends anything. Its attribute allowlist (`ATTRIBUTES` in `src/scrub.ts`) is the whole list: method, route, status, duration, request id, job name, outcome, counts, account and source ids (a row id of a mailbox or a job source, not a user id), error class, code and status, limit class, model id and token counts. A value must also look like an identifier (no spaces, no `@`, at most 80 characters), so a sentence is dropped even under a listed key.

- Errors: class name, a stack of function, file and line, the code and status, and the tags above. Never the message (only the fixed sentences written in this repo), the cause, request, headers, body, cookies or breadcrumbs.
- Request logs and metrics: method, route, status, time. The route comes from the router, never from the url a client typed: the rpc path of a procedure (`/rpc/answers/update`), its rest template (`/v1/answers/:id`), a fixed name such as `/health`, or `other`. A record id, a file key or a probe of random urls can't add a label. Each metric keeps at most 300 label sets and folds the rest into one `overflow` series, so a flood on one can't hide `skiffr.db.up` or the scheduler metrics.
- Model calls: model id, provider, token counts, finish reason, latency, outcome (`ok`, `budget`, `error`) and error class. Prompts and answers are added to the span only with `AI_TRACE_CAPTURE_CONTENT=true`, because they hold the applicant's data. Leave it off unless the collector is yours and you are debugging.
- Gmail and watcher failures: counted by kind in `skiffr.sync.failures`. Only `internal`, an error in our own code, is reported as an error. `upstream` (a Google 5xx, a response too large, a 4xx from Google), an expired grant, a rate limit or a dead careers page is Google's, the user's or the site's, and shows only as a metric.
- Umami: page views without query string, hash or referrer, record ids in the path rewritten to `:id`, nothing at all with Do Not Track or Global Privacy Control on. The api sends one event, `ai_budget_exhausted`, with no props that identify anyone.

`src/privacy.test.ts` feeds an error and attributes full of form values, an email, a resume line and a token through every sink and fails if any of it reaches the collector. It runs in `pnpm test`.

## Metrics

`skiffr.http.requests`, `skiffr.http.duration_ms`, `skiffr.db.up`, `skiffr.scheduler.runs`, `skiffr.scheduler.duration_ms`, `skiffr.scheduler.items`, `skiffr.scheduler.last_success_seconds` (per job: `gmail`, `watch`), `skiffr.sync.failures`, `skiffr.rate_limit.rejected`, `skiffr.ai.calls`, `skiffr.ai.tokens`, `skiffr.ai.duration_ms`. `skiffr.db.up` is set each time `/health` is called, so it needs a poller (the container healthcheck is one). Every request is also a log record, queued 500 at a time per 15 second flush with the oldest dropped first, so above about 30 requests per second some lines are lost, never the metrics. Alert on `last_success_seconds` going stale and on `skiffr.db.up` of 0.

## Setting it up

1. GlitchTip: create a project for the api (and one each for web and dashboard). Copy each dsn.
2. Umami: add a website per app (web, docs, dashboard, api) and copy the website ids.
3. OpenObserve: create a user for ingestion only and build `authorization=Basic <base64 of email:password>,stream-name=skiffr`. If OpenObserve is private to your tailnet, point the api at the address it has inside the Docker network (`http://openobserve:5080/api/default` on Dokploy), not the public hostname.
4. Keep the values in your secrets manager and put them in the app's environment in Dokploy, never in the repo. `scripts/dokploy-bootstrap.mjs --env-file` adds missing keys to the apps and never overwrites one that is set, see [deploy](https://docs.skiffr.findmalek.engineer/docs/deploy.md).
5. Check: the api logs `observability: errors, otlp, umami` at start. Test a dsn with
   `printf '%s\n%s\n%s' '{}' '{"type":"event"}' '{"message":"smoke test"}' | curl -X POST "https://<glitchtip host>/api/<project id>/envelope/" -H "X-Sentry-Auth: Sentry sentry_version=7, sentry_key=<key>" --data-binary @-`
   and look for the `skiffr` stream in OpenObserve after a few requests.

| Key | App | What it is |
| --- | --- | --- |
| `GLITCHTIP_DSN` | api, web, dashboard | the project's dsn |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | api | OTLP/HTTP base up to the org |
| `OTEL_EXPORTER_OTLP_HEADERS` | api | `key=value,key=value`, a secret |
| `AI_TRACE_CAPTURE_CONTENT` | api | `true` adds prompts and answers to model spans, default `false` |
| `UMAMI_URL`, `UMAMI_WEBSITE_ID` | all four | read at request time, so one image serves any site id. Web, docs and dashboard load `/analytics.js`, which does nothing when they are unset |

In the bootstrap env file the per app values are `UMAMI_<APP>_WEBSITE_ID` and `GLITCHTIP_WEB_DSN`, `GLITCHTIP_DASHBOARD_DSN`.

## Not done

- Browser side errors (web, dashboard): a browser SDK adds weight and reads the page. Server side render and route errors are reported.
- The extension has no third party tracker and none is planned. If wanted, an opt-in "send anonymous error reports" toggle, off by default, would post only the error class and extension version to your own api, which forwards it here. It is designed, not built.
- Langfuse, see the table. Request traces and spans for the schedulers: logs and metrics cover them for now.

---

# Privacy and data flow

URL: https://docs.skiffr.findmalek.engineer/docs/privacy
Markdown: https://docs.skiffr.findmalek.engineer/docs/privacy.md

> Exactly what leaves your machine, and where it goes.

skiffr is self-hosted. Your profile, answers and tokens are in your own Postgres, behind your own api. The extension is built to talk to no server except the api you configured and carries no tracker. The sites (landing page, docs, dashboard) can load your own Umami for page views, and the api can send error reports, logs and metrics to your own GlitchTip and OpenObserve, all off unless you set them and all from an allowlist, see [observability](https://docs.skiffr.findmalek.engineer/docs/observability.md).

The extension detects forms and fills them, and calls your api for that. After a fill it also sends the edits you make to your api, see below.

## Data flow

```text
web page -> extension -> your api -> your Postgres
                            |
                            +-> language model provider (Groq by default)
                            +-> embeddings provider (OpenAI, optional)
```

## What goes where

| To | What | When |
| --- | --- | --- |
| your api | field labels, names, placeholders, types and option texts of the form, your token. After a fill, also the filled and final values of the fields you edit (the extension cuts values at 301 characters, the api accepts up to 2000) | when you fill, and when you submit or leave the page |
| language model provider | the same field descriptors, your profile key names, and the values of an allowlist of profile keys | when a field needs mapping or an answer is drafted |
| embeddings provider | the normalized question label | only with `OPENAI_API_KEY`, and only for learning |
| your Umami, GlitchTip, OpenObserve | page views without query or referrer, error class and stack, request method, route and status, model id and token counts. Never form values, labels, resume or job text, tokens or the message of an error. Prompts and answers only with `AI_TRACE_CAPTURE_CONTENT=true` | only when you set the matching variable |
| nobody | form submissions | never |

### What the model sees of your profile

Key names are always sent, so the model can pick one. Values are sent only for the allowlist in `packages/ai/src/shared-keys.ts`:

- first and last name, city, country, work authorization and sponsorship, all links
- free-form fields labelled preferred name, headline, summary, experience, years of experience, skills, languages, notice period, availability, linkedin, github, portfolio or website

Email, phone, address, pay, ids and dates of birth are not on the list and stay out of every prompt. A value over 60 characters is not previewed in field mapping. Drafting an answer also sends the question, the job description and up to 5 of your earlier answers.

Password, hidden and file inputs are removed in code before a request is built. Text from pages and job posts is put in the prompt as escaped data blocks, and the model is told to treat it as data. The model's reply is checked in code: a profile key it invents becomes a skip.

The provider keeps what its own terms say. Leave the keys unset to send nothing: mapping and drafting then answer "No AI provider key is configured".

### What the extension does on a page

- the content script is injected on all pages, because an application form can be on any careers site. It looks for an application form and shows the toast. Nothing goes to your api until you say yes or press the shortcut
- the fill engine never submits a form and never clicks submit, next or apply buttons
- it never touches password or hidden inputs
- it sets a file only on a resume or CV upload slot, and only when the caller hands it a file
- it opens custom dropdowns (including `button[role=combobox]` widgets) and clicks their own options, and clicks the checkboxes and radios it fills, nothing else
- fields a person cannot see or reach (honeypots) are skipped

### What the api stores about learning

For every filled field the api keeps one event: the raw field label, the filled value and the final value, up to 2000 characters each, plus the site, the control type and an outcome (accepted, corrected, cleared). Answers you correct become learned answers, with an embedding of the question label only.

- fields with sensitive labels or autocomplete tokens, and values that look like a card number (Luhn), an IBAN or a US social security number, are never stored or filled
- events older than 90 days are deleted, but only inside the calls that record events or list suggestions, and 500 rows at a time. On a quiet account old events can stay until the next call
- events, answers and tokens are removed with the user row (`on delete cascade`). The dashboard has no self-service account deletion yet, so today that is an admin or database operation

### Gmail

Only when you connect it, see [Gmail job emails](https://docs.skiffr.findmalek.engineer/docs/gmail.md): skiffr reads unread inbox mail from the senders you watch, stores job title, company and link (not the email), and marks processed mail read, out of the inbox and labelled. No email text goes to a model provider.

### CV tailoring

Only when you connect it, see [CV tailoring](https://docs.skiffr.findmalek.engineer/docs/cv-tailoring.md): the text of your base resume, the shared parts of your profile and the job description you paste go to the AI provider to propose edits. Your Reactive Resume key is stored encrypted and never leaves the server. The base resume is only read; changes go to a copy.

### Job sources

Only for addresses you add, see [Job sources](https://docs.skiffr.findmalek.engineer/docs/sources.md): the api fetches those public pages and feeds with a request that names skiffr and carries no cookie or personal detail, and stores the title, company and link of each posting (not the page). The job links are never opened. No page text goes to a model provider.

### Tokens

The extension authenticates with a personal access token that starts with `skp_`. The server keeps its SHA-256 hash and a short display tail, never the token. In the extension the background worker and the options page read it. Content scripts on web pages are kept from it by `storage.local.setAccessLevel("TRUSTED_CONTEXTS")`, which needs Chrome 142 or newer (the manifest's `minimum_chrome_version`). Calls to the api are made by the background worker. A token can only call a fixed list of procedures (`TOKEN_PROCEDURES` in `packages/orpc/src/procedures.ts`): profile, answers, jobs, applications and the two ai calls. Account, auth and token management need a signed-in session. Set `EXTENSION_ORIGINS` to pin the api to your own extension id.

## Reporting a problem

Report vulnerabilities privately through GitHub, see `SECURITY.md` in the repo root.

---

# Product and roadmap

URL: https://docs.skiffr.findmalek.engineer/docs/roadmap
Markdown: https://docs.skiffr.findmalek.engineer/docs/roadmap.md

> Who skiffr is for, what job seekers complain about, where skiffr stands today, and what comes next.

This page is the product research behind the board ([#102](https://github.com/FindMalek/skiffr/issues/102)). It is opinionated on purpose and meant to be argued with. Every item on the roadmap is an issue on the [project board](https://github.com/users/FindMalek/projects/25).

## Vision

Applying for jobs is mostly retyping the same facts into forms that all behave differently. Tools that promise to do it for you tend to make things up, spam employers, hide behind a paywall and send your CV somewhere you cannot see. skiffr takes the other side:

1. **You stay the applicant.** It fills, you review, you press submit. It never invents a fact and never bypasses a captcha or a login.
2. **It gets better with use.** Corrections become answers, and it shows where every value came from.
3. **Your data stays yours.** Open source, self hosted, no analytics. A model is optional: it runs on your server with the key you configure, and it only sees what a feature needs, when you press it. Importing a CV sends the CV text, and you review the result before anything is saved.
4. **It covers the whole journey**, not only the form: finding jobs, checking they are real, the CV, the form, tracking replies, following up.

## Who it is for

| Persona | What they need | What would make them leave |
| --- | --- | --- |
| The active seeker (engineer, designer, analyst) applying to 5 to 20 jobs a week | Fast, correct fills on Greenhouse, Lever, Ashby, Workday; tailored CV; a queue; knowing what got a reply | A wrong visa or salary answer, a form left half filled with no explanation |
| The international applicant or career changer | Work authorization per country, other languages, other date and phone formats, relocation answers | An English only tool that guesses |
| The privacy minded self hoster | Own Postgres, no telemetry, clear list of what the model sees, easy upgrades and backups | Data leaving without a switch, a broken upgrade |
| The coach or helper (later) | A read only view of a client's queue and stats | Needing the client's password or profile |
| The contributor | A clear way to add an ats adapter or a language | No contract, no starter issues, slow reviews |

## What job seekers say

Method and honest limits: Reddit blocks the research crawler, so there are no first hand Reddit threads here. The evidence is Hacker News threads, Trustpilot pages, Firefox add-on reviews, the README of an open source Workday filler, community forums of two password managers and a set of surveys. Trustpilot and add-on reviews are self selected and not fact checked: a claim about a named product below is what its reviewers report, with the month of the review, not a finding of ours. Many comparison blogs are written by competitors, and those are marked as such and used only where nothing better exists. Ratings and prices move: prices were read in November 2026, check the vendor before you trust a number.

### Top 25 pains and desires

| # | Pain or desire | Evidence |
| --- | --- | --- |
| 1 | Retyping the same CV data into every form | [HN: Upload your resume and then type it out](https://news.ycombinator.com/item?id=30291081) (184 points, "if I have to retype my CV in your obnoxious web form, its just not worth the effort") |
| 2 | Workday: an account per employer, many pages, repeated sections | [HN thread](https://news.ycombinator.com/item?id=30291081) (a commenter calls making a new Workday account for each company the worst), [Workday filler README](https://github.com/pixotags/workday-application-autofill) ("the same 40-odd fields from scratch") |
| 3 | Workday widgets break fillers: React components, custom dropdowns, date spinners, value saved only on blur, multi step | [Workday filler README](https://github.com/pixotags/workday-application-autofill) |
| 4 | Autofill that makes things up or fills irrelevant fields | [Simplify on Trustpilot](https://uk.trustpilot.com/review/simplify.jobs) (a June 2026 reviewer says the AI "will lie by default"), [LazyApply on Trustpilot](https://ca.trustpilot.com/review/lazyapply.com) (a June 2026 reviewer reports consistent mistakes when applying) |
| 5 | Dangerous defaults on visa, sponsorship and veteran questions | [LazyApply on Trustpilot](https://ca.trustpilot.com/review/lazyapply.com) (a May 2026 reviewer reports a default "yes" that was incorrect on visa and veteran questions) |
| 6 | Dropdowns and education options missed or wrong, demographic answers wrong | [Simplify Firefox reviews](https://addons.mozilla.org/en-US/firefox/addon/simplify-jobs/reviews/) (December 2024: the degree dropdown is not filled when the degree is missing from the list; July 2023: skills and education fills fail when list options do not match; December 2021: no education on Workday forms), [review roundup](https://www.wobo.ai/blog/lazyapply-review/) (competitor blog, relays a report of wrong demographic data) |
| 7 | Blank or wrong name fields, an invented middle name | [LazyApply on Trustpilot](https://ca.trustpilot.com/review/lazyapply.com) (February and May 2026 reviewers report first and last name not entered or blanked), [review roundup](https://www.wobo.ai/blog/lazyapply-review/) (competitor blog, quotes a Reddit comment about a middle name added when there is none) |
| 8 | Spam: bots applying to roles outside the person's scope | [LazyApply on Trustpilot](https://uk.trustpilot.com/review/lazyapply.com?page=3) (2024 reviewers report applications to jobs outside their profile or filters) |
| 9 | Fear of account restrictions from automation on LinkedIn | [Scoutify](https://scoutify.com/blog/linkedin-auto-apply/) and [FastApply](https://blog.fastapply.co/can-you-get-banned-for-auto-applying-on-linkedin-2026) (both vendors, mostly temporary Easy Apply pauses, no independent count) |
| 10 | Ghost jobs: postings that never lead anywhere | [Enhancv survey](https://enhancv.com/blog/ghost-jobs-survey-2026-bls-data-comparison/) (47 percent say they applied to a role that did not exist), [Greenhouse via HR Review](https://hrreview.co.uk/hr-news/recruitment/one-in-three-uk-job-ads-may-be-fake-as-ghost-jobs-erode-trust-in-recruitment/385524), [Resume Genius via CPA Practice Advisor](https://www.cpapracticeadvisor.com/2026/04/30/ghost-jobs-still-haunting-67-of-job-seekers-report-finds/) |
| 11 | Applications vanish into a black hole, no status | [HN thread](https://news.ycombinator.com/item?id=30291081) ("black holes"), the praise for trackers in [Teal on Trustpilot](https://uk.trustpilot.com/review/tealhq.com) |
| 12 | Refund and cancellation disputes, trial to subscription surprises | [Simplify](https://uk.trustpilot.com/review/simplify.jobs) (refunds denied or delayed, a "3 months free" offer that was a 50 percent discount), [LazyApply](https://ca.trustpilot.com/review/lazyapply.com) (a June 2026 reviewer says it took two weeks to get a response to a refund request inside the 30 day window), [Jobscan](https://uk.trustpilot.com/review/jobscan.co) (a September 2026 reviewer says a trial turned into a paid plan early) on Trustpilot, as reported by reviewers |
| 13 | Price and paywalls: autofill free, everything else paid | [Huntr pricing](https://huntr.co/pricing) (free plan tracks up to 100 jobs, Pro $40 a month or $30 a month billed quarterly), [Simplify+ pricing](https://help.simplify.jobs/articles/5623502-whats-included-in-simplify-features-and-pricing) ($39.99 a month, $89.99 a quarter, basic autofill and tracker free), [Teal+ price](https://toolradar.com/tools/teal-hq/pricing) (third party, $29 a month as of October 2026), [AIApply credit packs on top](https://www.resumly.ai/best/best-job-application-bots) (third party reported, the vendor site shows no prices) |
| 14 | A tool that is slow or heavy in the browser | [Simplify Firefox reviews](https://addons.mozilla.org/en-US/firefox/addon/simplify-jobs/reviews/) (June 2024 to October 2026: reviewers report RAM and CPU spikes and freezes, on Workday pages in two of them) |
| 15 | Login loops, profile not connecting | [Simplify Firefox reviews](https://addons.mozilla.org/en-US/firefox/addon/simplify-jobs/reviews/) (December 2023, August 2025 and October 2025 reviewers say the extension keeps asking to log in or cannot reach their profile) |
| 16 | Parsed or pre filled CV data comes out garbled | [HN thread](https://news.ycombinator.com/item?id=30291081) (LaTeX and multi column PDFs) |
| 17 | File format friction and CV upload quirks | [HN thread](https://news.ycombinator.com/item?id=30291081) |
| 18 | Generic, robotic cover letters that need a heavy edit | [Teal on Trustpilot](https://uk.trustpilot.com/review/tealhq.com) (a May 2026 reviewer: cover letters "usually need a heavy edit"), [Jobscan on Trustpilot](https://uk.trustpilot.com/review/jobscan.co) (a September 2026 reviewer: generated bullets "sound stiff and need manual editing"), recruiter side view in [Cake](https://www.cake.me/resources/job-searching-guide/ai-to-write-cover-letter) (vendor) |
| 19 | Support that does not answer | [LazyApply](https://ca.trustpilot.com/review/lazyapply.com) (2026 reviewers report no replies to support emails), [Simplify](https://uk.trustpilot.com/review/simplify.jobs) (reviewers describe slow or unresponsive support) on Trustpilot |
| 20 | Where does my CV go: unclear privacy and which AI vendor sees it | [JobWizard guide](https://jobwizard.ai/blog/are-job-application-autofill-extensions-safe-to-use) (vendor blog) tells people to check what an autofill extension reads and stores |
| 21 | Password managers are built for logins, not job forms: custom fields need setup and are not offered inline | [1Password community](https://www.1password.community/1password-at-home-31/use-custom-fields-for-autofill-possible-in-1password-5285) (a September 2023 staff reply: custom fields "won't appear in the inline menu or be filled with a shortcut", the feature request was still open in September 2026), [Bitwarden help](https://bitwarden.com/help/auto-fill-custom-fields/) (custom fields are set per item and "typically" fill in form or input elements) |
| 22 | Tools that report "applied" when it never reached the employer | [Remote Job Assistant on Sonara](https://www.remotejobassistant.com/blog/sonara-ai-review) (competitor blog, relays user reports of silent failures at email verification steps, could not reach the vendor site, unverified) |
| 23 | Distrust of ATS scores and keyword games | mixed accuracy in [Jobscan on Trustpilot](https://uk.trustpilot.com/review/jobscan.co); [Jobscan on ATS and AI detection](https://www.jobscan.co/blog/can-ats-detect-ai-resume/) (vendor) |
| 24 | A cheap way to tailor a CV per job and see missing keywords | the top praise for Huntr and Jobscan in [Huntr](https://uk.trustpilot.com/review/huntr.co) and [Jobscan](https://uk.trustpilot.com/review/jobscan.co) Trustpilot reviews |
| 25 | Autofill that still leaves cleanup, and the employer side backlash against auto apply | [JobCopilot on Simplify](https://jobcopilot.com/simplify-jobs-review/) (competitor blog, quotes Reddit users: "glorified autofill", one Reddit user is paraphrased as saying fixing errors took longer than applying by hand), [Inquirer on employers and auto apply](https://www.inquirer.com/business/ai-resum-jobs-applications-employers-artificial-intelligence-hiring-20260301.html) (an HR officer calls auto apply services "snake oil") |

What people love, in short: free autofill that works on common systems (Simplify), a tracker that keeps the search organized (Teal, Huntr), keyword gap feedback (Jobscan, Huntr), and time saved when the fills are right.

### Competitors at a glance

| Product | Kind | What reviewers like | What reviewers report as problems | Price signal (verify) |
| --- | --- | --- | --- | --- |
| Simplify | Autofill and tracker, free core | Free autofill, broad ats coverage | Missed dropdowns and Workday education, refund disputes, performance on Firefox | Simplify+ $39.99 a month, $89.99 a quarter |
| Teal | Tracker and resume tools | Easy tracker, keyword analysis | Cover letters needing heavy edits, listings that feel like ghost jobs, email volume | Teal+ about $29 a month (third party) |
| Huntr | Tracker and tailoring | Tailoring, kanban, keyword feedback | One reviewer found auto fill hit or miss | Free up to 100 jobs, Pro $40 a month |
| LazyApply | Auto apply bot | Volume, some interviews | Wrong or blank fields, jobs outside the person's profile, refund delays, little support | Subscription |
| Sonara, JobCopilot, AIApply | Auto apply services | Hands off | Competitor blogs relay billing and renewal complaints, AIApply sells credit packs on top of a subscription | Trial then recurring, credit packs (third party reports) |
| Jobscan | Resume scoring and building | Keyword gap analysis | Billing and cancellation disputes, stiff AI text, mixed score accuracy | Subscription |
| LinkedIn Easy Apply bots | Automation | Easy Apply is liked by many | Account restriction risk, terms of service | Varies |
| Chrome, Bitwarden, 1Password autofill | General form fill | Already installed | Built for logins and addresses: custom fields need setup | Free or bundled |

skiffr's lane: the autofill and answer memory of Simplify, the queue and funnel of Teal and Huntr, CV tailoring that cannot invent facts, all in a place the user owns.

## Where skiffr stands today

Status is as of this page: solved means it works and is tested, partial means it exists with known limits, unsolved means nothing yet.

| Area | Status | What exists | What is missing | Issues |
| --- | --- | --- | --- | --- |
| Detect forms, ask, fill | solved | Greenhouse, Lever, Ashby, Workable adapters, toast, shortcut, iframes (same origin) | Cross origin iframes | [#131](https://github.com/FindMalek/skiffr/issues/131) |
| Fill engine (React safe, selects, comboboxes, shadow dom) | partial | Works on fixtures and the four ats | Known gaps in [#48](https://github.com/FindMalek/skiffr/issues/48) | [#48](https://github.com/FindMalek/skiffr/issues/48) |
| Workday and account walls | unsolved | `myworkdayjobs.com`, `icims.com` and SmartRecruiters hosts are detected | No adapter for any of them, no multi page flow, no hand over | [#127](https://github.com/FindMalek/skiffr/issues/127), [#128](https://github.com/FindMalek/skiffr/issues/128), [#129](https://github.com/FindMalek/skiffr/issues/129), [#130](https://github.com/FindMalek/skiffr/issues/130) |
| Never submit, honeypots, hidden fields | solved | Enforced and tested | Keep testing per adapter | |
| Sensitive fields | partial | Central guard in five languages | Long tail of wording | [#98](https://github.com/FindMalek/skiffr/issues/98), [#120](https://github.com/FindMalek/skiffr/issues/120) |
| Learning from corrections | solved | Log, lookup, suggestions, per site profile | Stale answers, scope, never learn | [#115](https://github.com/FindMalek/skiffr/issues/115), [#116](https://github.com/FindMalek/skiffr/issues/116), [#117](https://github.com/FindMalek/skiffr/issues/117) |
| Onboarding (profile from a CV) | unsolved | A typed profile form | Import and a first run checklist | [#107](https://github.com/FindMalek/skiffr/issues/107), [#108](https://github.com/FindMalek/skiffr/issues/108), [#109](https://github.com/FindMalek/skiffr/issues/109), [#110](https://github.com/FindMalek/skiffr/issues/110) |
| Resume upload | unsolved | A file fill primitive that nothing feeds | User confirmed attach, tailored PDF | [#123](https://github.com/FindMalek/skiffr/issues/123) |
| CV tailoring | solved | Reactive Resume copy, extractive edits, keyword score | Posting is pasted, not tried on a real instance ([#88](https://github.com/FindMalek/skiffr/issues/88)) | |
| ATS score honesty | solved | Plain counting, docs say it is not an ats score | | |
| Cover letters | unsolved | | Draft per job | [#125](https://github.com/FindMalek/skiffr/issues/125) |
| Free text screening answers | partial | The api can draft an answer, the extension does not call it | Review flow | [#124](https://github.com/FindMalek/skiffr/issues/124) |
| Work authorization and visa | partial | Profile has the data | Deterministic answers per country | [#118](https://github.com/FindMalek/skiffr/issues/118) |
| Salary expectations | partial | Min and max in the profile | Policy, currency, never fill default | [#126](https://github.com/FindMalek/skiffr/issues/126) |
| Dates, phone, number formats | partial | Date and number helpers | Phone format, ambiguity rules by field | [#119](https://github.com/FindMalek/skiffr/issues/119) |
| Names and address | partial | First and last name, city, region, country and postal code | Middle and preferred name, street address lines, a full name composer, address widgets | [#107](https://github.com/FindMalek/skiffr/issues/107), [#121](https://github.com/FindMalek/skiffr/issues/121) |
| Other languages | partial | Sensitive lists in en, fr, de, es, ar | Field matching synonyms | [#122](https://github.com/FindMalek/skiffr/issues/122) |
| Captcha, bot checks | unsolved | Nothing is bypassed, but nothing is said | A calm hand over | [#129](https://github.com/FindMalek/skiffr/issues/129) |
| Duplicate applications | partial | One queue row per canonical url | Same company and role, cooldown, toast warning | [#133](https://github.com/FindMalek/skiffr/issues/133) |
| Ghost and closed postings | unsolved | | Signals and badges | [#132](https://github.com/FindMalek/skiffr/issues/132) |
| Application tracking | partial | Manual statuses, funnel stats, Gmail job alert import | Reply detection, reminders, deadlines | [#135](https://github.com/FindMalek/skiffr/issues/135), [#136](https://github.com/FindMalek/skiffr/issues/136) |
| Personas, referrals, analytics by what works | partial | Stats by source, ats, role, match score | Per resume persona, referrals | [#138](https://github.com/FindMalek/skiffr/issues/138), [#137](https://github.com/FindMalek/skiffr/issues/137) |
| Bulk apply safety | partial | Api rate limits, never auto submit | Pacing and quality gate for next job | [#134](https://github.com/FindMalek/skiffr/issues/134) |
| Trust: why a value, undo, dry run, per site off | partial | Outlined uncertain fields, "don't ask on this site" | Provenance panel, undo, dry run, list | [#113](https://github.com/FindMalek/skiffr/issues/113), [#114](https://github.com/FindMalek/skiffr/issues/114) |
| Failure modes | partial | Clear errors on some paths | Offline mode, version handshake, report a broken site | [#139](https://github.com/FindMalek/skiffr/issues/139), [#112](https://github.com/FindMalek/skiffr/issues/112), [#140](https://github.com/FindMalek/skiffr/issues/140), [#20](https://github.com/FindMalek/skiffr/issues/20) |
| Other browsers, phone | unsolved | Chrome 142 plus only | Edge, Firefox, share to queue from a phone | [#141](https://github.com/FindMalek/skiffr/issues/141), [#142](https://github.com/FindMalek/skiffr/issues/142) |
| Data export, import, delete | unsolved | | gdpr export and erase, JSON Resume | [#111](https://github.com/FindMalek/skiffr/issues/111), [#109](https://github.com/FindMalek/skiffr/issues/109) |
| Self hosting upgrades, backups | partial | Deploy guide, backup workflow | Restore drill, upgrade guide, tagged releases | [#147](https://github.com/FindMalek/skiffr/issues/147), [#145](https://github.com/FindMalek/skiffr/issues/145), [#31](https://github.com/FindMalek/skiffr/issues/31) |
| Accessibility | unsolved | | Audit of the toast, panels and dashboard | [#146](https://github.com/FindMalek/skiffr/issues/146) |
| Open source health | partial | Contributing guide, code of conduct, ci | Adapter contract, starter issues, translations | [#143](https://github.com/FindMalek/skiffr/issues/143), [#144](https://github.com/FindMalek/skiffr/issues/144) |
| Coach and team sharing | unsolved | | Not started, see ideas below | |
| Interview prep | unsolved | Notes board | Not started, see ideas below | |

## Edge cases and designs

Short answers to the hard cases, with where each lands.

- **Account walls (Workday and others).** skiffr never types a password and never creates an account. It detects the wall, says "your turn", and offers the fill again afterwards. A ledger of which tenant you have an account at, with the email used and no password, helps people who sign up for twenty companies ([#129](https://github.com/FindMalek/skiffr/issues/129), [#130](https://github.com/FindMalek/skiffr/issues/130)). An optional application email or alias in the profile keeps signups apart from the main inbox.
- **Resume upload.** The person picks the PDF once in the extension options, and confirms the attach on each form. The tailored PDF from CV tailoring can be pulled in per job. Cover letter and photo slots never get the resume ([#123](https://github.com/FindMalek/skiffr/issues/123)).
- **Cover letters and free text.** Drafts come from the profile, the tailored CV and the posting. Numbers, employers and dates must exist in the sources or the draft is refused. Drafts are outlined, labelled and undoable, and an edit is learned ([#124](https://github.com/FindMalek/skiffr/issues/124), [#125](https://github.com/FindMalek/skiffr/issues/125)).
- **Salary.** Never filled by default. A policy per person (range, target, never) and per currency. A "current salary" question stays empty and outlined, because asking is illegal in some places. A negotiation note per job stays local ([#126](https://github.com/FindMalek/skiffr/issues/126)).
- **Work authorization, relocation, remote.** Answered by rules from structured data, never by the model. Unknown means empty and outlined, never a default yes ([#118](https://github.com/FindMalek/skiffr/issues/118)).
- **Formats.** Dates follow the field first, the locale second, and stay empty when ambiguous. Phones are stored as E.164 and shaped per field. Names carry parts, a preferred name and a transliteration slot ([#119](https://github.com/FindMalek/skiffr/issues/119), [#107](https://github.com/FindMalek/skiffr/issues/107), [#121](https://github.com/FindMalek/skiffr/issues/121)).
- **Captcha and bot checks.** Never bypassed. Hand over to the person, then re arm ([#129](https://github.com/FindMalek/skiffr/issues/129)).
- **Duplicates and volume.** A warning, not a block: same company and title, a cooldown after a recent application, and a pacing prompt in "open next" ([#133](https://github.com/FindMalek/skiffr/issues/133), [#134](https://github.com/FindMalek/skiffr/issues/134)). skiffr will not become an auto apply bot: that is the line between it and the tools users complain about.
- **Ghost jobs.** Signals with reasons, never a hidden score, and one click to say "it is open" ([#132](https://github.com/FindMalek/skiffr/issues/132)).
- **Tracking.** Reply emails become suggestions the person confirms. skiffr stores the status, company and date, never the mail ([#135](https://github.com/FindMalek/skiffr/issues/135)). Reminders and deadlines come out as a private ics feed, with no calendar login ([#136](https://github.com/FindMalek/skiffr/issues/136)).
- **Learning quality.** Facts expire (notice period, availability), answers have a scope (this site, this ats, global) with a conflict view, and the person can mark a field "never learn" ([#116](https://github.com/FindMalek/skiffr/issues/116), [#117](https://github.com/FindMalek/skiffr/issues/117), [#115](https://github.com/FindMalek/skiffr/issues/115)).
- **Trust.** A panel with the source of each value, undo per field and for the whole fill, and a dry run ([#113](https://github.com/FindMalek/skiffr/issues/113), [#114](https://github.com/FindMalek/skiffr/issues/114)).
- **Failure modes.** Offline cache and queued learning, model down falls back to saved answers, a version handshake between extension and api, and a "this site did not work" report that shows exactly what it would share ([#139](https://github.com/FindMalek/skiffr/issues/139), [#112](https://github.com/FindMalek/skiffr/issues/112), [#140](https://github.com/FindMalek/skiffr/issues/140)).
- **Mobile and other browsers.** Extensions do not run on phones, so the phone adds jobs to the queue through a share target and the form is done on a laptop ([#142](https://github.com/FindMalek/skiffr/issues/142)). Edge and Firefox are builds, Safari is a plan ([#141](https://github.com/FindMalek/skiffr/issues/141)).
- **Data rights.** Export everything, delete everything, import JSON Resume and the LinkedIn archive ([#111](https://github.com/FindMalek/skiffr/issues/111), [#109](https://github.com/FindMalek/skiffr/issues/109)).
- **LinkedIn Easy Apply and Indeed Apply.** Open question, listed in the ideas below and not an issue yet. A person driven fill of those modals is not the same as a bot, but both sites forbid automation in their terms and users report restrictions. Until there is a clear reading of the terms skiffr does not touch them. Decide before building.

## Roadmap

Ordering rule: first value, then trust, then the pains people name most, then breadth. Nothing here makes skiffr submit for you.

### Now

Why: a new person should reach a correct fill in minutes, see why a value was used, and never get a wrong answer on the questions that reject an application. Then Workday, the pain every source names.

| Issue | Item | Size |
| --- | --- | --- |
| [#107](https://github.com/FindMalek/skiffr/issues/107) | profile: work history, education and address | M |
| [#108](https://github.com/FindMalek/skiffr/issues/108) | profile: import a cv with the model, review before save | L |
| [#110](https://github.com/FindMalek/skiffr/issues/110) | dashboard: first run wizard, first fill in 3 minutes | M |
| [#113](https://github.com/FindMalek/skiffr/issues/113) | extension: why this value, undo and diff after a fill | M |
| [#114](https://github.com/FindMalek/skiffr/issues/114) | extension: dry run mode and per site disable list | S |
| [#112](https://github.com/FindMalek/skiffr/issues/112) | api: version handshake between extension and api | S |
| [#145](https://github.com/FindMalek/skiffr/issues/145) | ci: tagged releases with changelog and extension zip | S |
| [#118](https://github.com/FindMalek/skiffr/issues/118) | fill: work authorization and sponsorship from structured data | M |
| [#119](https://github.com/FindMalek/skiffr/issues/119) | fill: phone, date and number formats per field | M |
| [#123](https://github.com/FindMalek/skiffr/issues/123) | extension: attach my cv with a file the person confirms | M |
| [#127](https://github.com/FindMalek/skiffr/issues/127) | extension: workday adapter and tenant flow | L |
| [#128](https://github.com/FindMalek/skiffr/issues/128) | extension: multi step and spa forms keep state | M |
| [#129](https://github.com/FindMalek/skiffr/issues/129) | extension: hand over on captcha, login and account walls | M |
| [#133](https://github.com/FindMalek/skiffr/issues/133) | jobs: duplicate and cooldown guard | M |
| [#134](https://github.com/FindMalek/skiffr/issues/134) | extension: guardrails for applying to many jobs | S |
| [#111](https://github.com/FindMalek/skiffr/issues/111) | account: export all my data and delete my account | M |

### Next

Why: the answer bank gets smarter, the journey after the form gets tracked, and the project becomes easy to contribute to. [#120](https://github.com/FindMalek/skiffr/issues/120) is an evaluation only: it decides whether a model beats word lists for sensitive fields before anything is built.

| Issue | Item | Size |
| --- | --- | --- |
| [#109](https://github.com/FindMalek/skiffr/issues/109) | profile: import json resume and linkedin data export | M |
| [#115](https://github.com/FindMalek/skiffr/issues/115) | learning: never learn this field | S |
| [#116](https://github.com/FindMalek/skiffr/issues/116) | learning: expiring answers and facts | M |
| [#117](https://github.com/FindMalek/skiffr/issues/117) | learning: answer scope per site, ats or global, with conflict view | M |
| [#121](https://github.com/FindMalek/skiffr/issues/121) | fill: name parts and address autocomplete widgets | M |
| [#122](https://github.com/FindMalek/skiffr/issues/122) | fill: match labels in other languages | M |
| [#120](https://github.com/FindMalek/skiffr/issues/120) | fill: model assisted sensitive field classifier (evaluate regex vs embeddings vs llm) | eval |
| [#124](https://github.com/FindMalek/skiffr/issues/124) | extension: draft free text answers for review | M |
| [#125](https://github.com/FindMalek/skiffr/issues/125) | cv: cover letter draft per job, reviewed before use | M |
| [#126](https://github.com/FindMalek/skiffr/issues/126) | profile: salary expectation policy and negotiation notes | M |
| [#131](https://github.com/FindMalek/skiffr/issues/131) | extension: cross origin iframes for fill and learning | M |
| [#132](https://github.com/FindMalek/skiffr/issues/132) | jobs: detect closed and ghost postings | M |
| [#135](https://github.com/FindMalek/skiffr/issues/135) | gmail: detect rejections and interviews, update status | L |
| [#136](https://github.com/FindMalek/skiffr/issues/136) | dashboard: follow up reminders, deadlines and an ics feed | M |
| [#138](https://github.com/FindMalek/skiffr/issues/138) | dashboard: resume personas per job type and stats per persona | M |
| [#139](https://github.com/FindMalek/skiffr/issues/139) | extension: api down and model down modes | M |
| [#140](https://github.com/FindMalek/skiffr/issues/140) | extension: report a broken site with a sanitized snapshot | M |
| [#143](https://github.com/FindMalek/skiffr/issues/143) | extension: adapter contract, contributing guide and good first issues | M |
| [#146](https://github.com/FindMalek/skiffr/issues/146) | accessibility: toast, panels and dashboard audit | M |
| [#147](https://github.com/FindMalek/skiffr/issues/147) | deploy: restore drill and upgrade guide | M |

### Later

Why: valuable, but they depend on the above or carry more risk.

| Issue | Item | Size |
| --- | --- | --- |
| [#130](https://github.com/FindMalek/skiffr/issues/130) | dashboard: which ats accounts I have, without passwords | S |
| [#137](https://github.com/FindMalek/skiffr/issues/137) | dashboard: referrals on jobs and in stats | S |
| [#141](https://github.com/FindMalek/skiffr/issues/141) | extension: firefox and edge builds, safari plan | M |
| [#142](https://github.com/FindMalek/skiffr/issues/142) | dashboard: pwa and share target to queue jobs from a phone | M |
| [#144](https://github.com/FindMalek/skiffr/issues/144) | dashboard and extension: translations setup | M |

Already on the board and kept as they are: learned http replay recipes ([#18](https://github.com/FindMalek/skiffr/issues/18), after the trust items above), read only smoke across real ats sites ([#20](https://github.com/FindMalek/skiffr/issues/20)), the Chrome Web Store account ([#26](https://github.com/FindMalek/skiffr/issues/26)), and the follow up issues from earlier reviews.

### Ideas without an issue yet

- **Team and coach sharing.** A read only link to a person's queue and stats, with no profile and no answers. Large, depends on the data export work.
- **Interview prep sheet per application.** Questions and stories drawn from the person's own answer bank and the posting, never invented experience.
- **Learning quality replay.** A harness that replays correction logs and reports hit rate by source, correction rate and stale rate, run in ci on fixtures. Follows the recorded real model eval ([#41](https://github.com/FindMalek/skiffr/issues/41)).
- **LinkedIn Easy Apply and Indeed Apply.** See the edge case above: a terms reading comes first, then maybe an issue.
- **Safari.** An app store build costs money and a native wrapper. Only after Edge and Firefox.
- **A browser independent fill bookmarklet** for pages where an extension is blocked. Low priority and hard to keep safe.

## How this page is kept

When an item ships, move it to the gap table as solved and delete the row from the roadmap. When a pain shows up in a bug report or a review more than twice, add it to the top 25 with the link. The reviewer guide in [`.github/REVIEW.md`](https://github.com/FindMalek/skiffr/blob/main/.github/REVIEW.md) is updated the same way with new bug classes.