# Key decisions What was decided for roledesk and the one reason for each. The longer reasoning is in `../news/docs/JobBoardPlan/roles-build-plan.md` and `jobhunt-hq-assessment.md`. ## Shape **Built on the boilerplate, with `desk` copied from news.** `pipeline/` (queue and scheduler, pipeline 2.0), `auth/` and `deploy/` come from `../boilerplate` and `desk/` from `../news`, all four as downstream copies refreshed with `git archive`. A fix lands upstream first, or the next refresh reverts it. The package is `app`, per the boilerplate rule, since the deploy kit and the `APP_*` variables assume it. **The domain noun is `role`.** `jobs/` keeps meaning the work the app queues, so "job" never has two senses in one sentence. **Own database, queue and port.** `roledesk.db`, `config.yaml`, port 8790. A shared file with newsdesk would buy "articles about this company" by cosine, which is worth less than two apps that can migrate independently. **Storage is written, not imported.** `desk` has no storage package on purpose, so ~120 lines of connection plumbing are copied from newsdesk. If the same edit lands in both a second time, a shared `Connection` moves into `desk` below `pipeline`. **Layers are `models, places, seniority, config, storage, jobs, web, main, cli`.** `places` and `seniority` read what a board wrote and know no database, so they sit under `config` and storage may use them. `tests/test_architecture.py` holds the direction and the doors within `app`; `tests/test_coupling.py` holds that `pipeline`, `auth` and `desk` import nothing from `app` or each other, except `desk` from `pipeline`, and that a plugin imports `desk` only. ## Data **Two open roles are one posting when company, title, country and a town agree** (`app/dupes.py`). Same non-empty `company_key`, same `title_key`, the same country (the column, or the one the place names when the column is empty or `EU`), and town sets from `places.towns` that share a member, or no town on one side. Host does not matter: on 2026-09-29, 1,080 of 33,881 open roles were copies, 14 of them across hosts (Jobindex or Platsbanken beside the company's board) and the rest one board listing one role under several ids, as SAP does under 3 to 9. The stored `(company_key, title_key, place_key)` found none of the cross-host pairs, since `Ballerup` and `Ballerup, Denmark` differ, and newsdesk's `location_key OR title_key` would merge the same title at two companies. The same title in Berlin and Munich stays two roles, so a place filter finds each. `places.towns` reads the first comma part of each place, so `Mountain View, California` and `San Francisco, California` share no town. **A group is rows that all match each other, never a chain.** A row with no place matches Belgium and the Netherlands, a row with no country matches Japan and Malaysia, and joining on one match merged both pairs on the live data. Rows are taken sharpest first (a town, then only a country, then neither) and join a group only when they match every member; a vaguer row joins a group of its own tier, else the one sharper group it fits, else starts its own. A known miss: `Remote - USA NH` and `Remote - USA WA` merge, since a state code is not a town. **A copy is stored as `roles.dup_of` and rebuilt after every pull.** The feed, its counts and facets, the tag and company counts, scoring, embedding, extract and summarise all add `dup_of IS NULL`, which keeps `idx_roles_posted` usable where a window function over the filtered rows would scan them all. The kept role is a board over a search provider, then one with a description, then the earliest `posted_at`, then the smallest uid. `close_boards` rebuilds from scratch in 0.3 s after its closes, and so do `set_fetch` and `remove_search` when they close roles, so a closed kept role hands its group to the next copy. Where a group changed, the kept role takes the earliest `read_at` and each agent's latest vote from its copies and the role it replaces; an unchanged group is left alone, so marking a role unread again sticks. The per-board counts on the Sources page still count copies, since they report what a board holds. A feed row shows `×N` for N postings and the reader lists them under "Also posted", newsdesk's "Also covered by"; a copy opened by its link says which role the feed lists instead. **`place`, `country` and `remote` are separate columns.** `location` already means where an `Item`'s original lives. `remote` alone over-matches, because boards write "UK | Remote", so a gate on remote also reads `country`. **`raw` is transport, columns are storage.** No `Item.facets`. A plugin puts structured fields in `raw` under the column's name and `upsert_role` unpacks them into indexed columns, which is where gates query them. An empty value never overwrites a filled column, so a terse board does not erase what `extract` found. **`extract` fills, the board wins.** `set_extracted` writes a model's value only into an empty column. A board's structured field is first-party, and `upsert_role` would put it back on the next pull anyway, so letting the model replace it would make a column flip between two answers. `place` brings `place_key` with it, which only ever moves a role from the empty place key to a real one. **`function` is the one column where the model wins, because the board never filled it.** `classify(department, title)` in `plugins/ats.py` is `ats`'s own keyword guess, not a board field, so "the board wins" does not apply to it: `set_extracted` writes a non-empty `function` over the guess outright, rather than only into an empty column, and `upsert_role` then leaves `function` alone for any role with `extracted_at` set, whatever the classifier says on the next pull. A role not yet extracted still gets a fresh guess every pull, the same as any other raw field. One rule, so `function` cannot flip between the classifier's answer and the model's on alternating pulls, which is exactly what "the board wins" above was written to prevent for a real board field. **`classify` matches whole words, not substrings, and checks the title before the department.** The ported version matched substrings, so `" it"` (meant to catch an "IT" department) matched inside "Italy" and "Italia", filing European sales roles ("Commercial Italy") as engineering; it now requires a word boundary, doubled on both sides for the handful of short tokens ("it", "seo", "qa", "ux", ...) that are themselves the start of an unrelated word ("Seoul", "Qatar"), while the rest keep a leading boundary only, since most are deliberate stems ("manag", "engineer", "recruit") meant to also match "management", "engineering", "recruiting". A department is often a generic umbrella ("Operations", "Engineering & Product") that says less than the title does, so the title is checked first and the department is the fallback; a hand-checked sample of 60 roles where the two orders disagreed found title-first right about twice as often. Nothing matching returns `''`, not `"other"`, which claimed a knowledge the classifier does not have. A modest set of German, Dutch, Danish, Norwegian, Swedish and French keywords (developer/engineer, sales) covers the seed's other languages; it is deliberately not complete, since `extract` is the rest. **Structured pay is unpacked the same as any other board field, except that Greenhouse and Ashby need an extra query parameter to get it.** Ashby sends it with `?includeCompensation=true`, Lever's `salaryRange` and Recruitee's `salary` are already on the plain list response, and Greenhouse needs `pay_transparency=true` on the same request it already makes (no per-role fetch); Personio's XML rarely carries a `salaryInformation` block, but reads the same way when it does. Workable and SmartRecruiters give neither, checked live against their real boards (2026-09-29). Every host converts to yearly `salary_min`/`salary_max`/`currency`: a monthly figure is multiplied by 12, an hourly or a daily one is left out rather than annualised into a number nobody stated, and a range with no currency is ignored. Greenhouse can give several ranges for one role (one per office or pay zone); with more than one there is no way to tell which office the role in hand is at, so all of them are skipped rather than one being picked at random. **Pay that does not normalise is not dropped, only kept out of the gate columns.** `roles.salary_text` (migration 12) is one human-readable line per parser, written whether or not the board's pay conformed (an hourly or a daily rate, several Greenhouse pay zones, a range with no currency), so a person can read it and do their own sums; it is filled through `raw` like the other columns, but replaced whole on every pull, including with `''` when a board stops stating pay, since the usual keep-filled rule (`_RAW_TEXT`) would otherwise leave a stale line behind. `salary_state` (`app.models.Role`) is derived, not stored: 'normalised' when `salary_min` or `salary_max` is set, 'stated' when only `salary_text` is, `''` otherwise; it is what the feed's Pay filter and badge read, and gates and scoring keep reading only `salary_min`/`salary_max`/`currency`, unchanged. **`extract` reads the board's location too.** The model gets title, the board's `place` text, and the first 3000 characters of the description. Greenhouse's location line ("Berlin, Germany") is often the only place a country is stated, and it is part of the posting, so the "only what the posting states" contract still holds. **`country` is filled from `place` by a lookup, before `extract`.** `country_of` maps the location line to an ISO code from every ISO country by its English name (and its own-language name for a European one) and the cities the boards name most, where `extract` would be a paid call per role for the same answer. On the live data (2026-09-29) 7.0% of open roles resolve to nothing, down from 16.8%, and most of those write only "Hybrid", "Remote" or a region such as "Americas". The line is folded by `_place_fold`, which also maps ł, đ, ø and æ since NFKD leaves them whole; `_fold` stays as it is because it builds `company_key`. Within one location (the line split at `;`, `|` and `/`) the widest unit named wins: a country beats a US state or a Canadian province, which beats a city, so "London, Ontario" is CA and "Tilburg, NB, Netherlands" is NL. A state code that is also a country's (DE, CO, MA, IN) counts as the state only when the line also names a US place, so "Bogota, CO" is CO and "Paderborn, DE" is ''. A line naming several countries is `EU` when all of them are European (the UN's Europe, plus Cyprus, Turkey and the Council of Europe's Caucasus members) and '' otherwise: "Dublin, London" is EU, "Remote, EU or US" is ''. `EU`, ISO's reserved code, also stands for "Remote - Europe" and "EMEA", so a Europe gate is a list of codes that includes it; a country beats the region it is in ("London, EMEA" is GB). `backfill_from_place` only fills an empty column, so a fix that changes answers comes with a migration: v12 recomputes `country` for every role `extract` has not read and whose board sent no `country` in `raw`, which changed 1,705 open roles, 48 of them from one code to another or to '' (25 Hong Kong roles moved from CN to HK). **`permit` and `languages` are columns, and so is `extract_tries`.** `permit` answers the plan's open item 1 (visa sponsorship as a gate field) while nothing depends on it yet. newsdesk keeps give-up counts in `raw`; here `upsert_role` rewrites `raw` on every pull, which would reset the count, so the counter is its own column. **Postings are persisted.** Storing every posting is what gives `first_seen`, when the app itself first stored the role, and `closed_at`, set by `mark_closed` when a complete fetch of a board no longer lists a role. A role listed again is open again. **`posted_at` (migration 10) is the earlier of `first_seen` and a trusted host's `published_at`; `first_seen` is left alone, as when the app found the role.** `first_seen` being the only honest posted date was true of Greenhouse's `updated_at`, which resets on every edit; `plugins.ats` already reads `first_published` instead, and that plus the other hosts' dates (Lever's `createdAt`, Ashby's `publishedAt`, SmartRecruiters' `releasedDate`, Recruitee's `published_at`/`created_at`, Personio's `createdAt`, Workable's `published`, and the two `search` providers' (Jobindex's RSS `pubDate`, Adzuna's `created`)) are creation dates, checked against live boards and the live database (`app.models.TRUSTED_POSTED_HOSTS`, with the evidence in its comment). A date in the future or before 2015 is not trusted either, host or no host. Without this, a newly added board's whole backlog scored as freshly posted for two weeks: on the live database, 10,223 of 15,415 board roles were posted more than 30 days before they were first seen (average gap in days: Ashby 78, Greenhouse 143, Lever 226, Personio 333), and open roles with `recency` (`app.jobs.score.recency`) above 0.5 fell from all 15,558 of them to 3,089 (19.9%) once it read `posted_at` instead. `upsert_role` keeps the earliest `posted_at` a role has ever had: an edit on the board can only move its own date later, never earlier, so it can only move `posted_at` earlier too, when the board finally reports the true one. `TRUSTED_POSTED_HOSTS` is gone: each reader declares `Fields(posted="trusted")`, read through `app/models.py`, and there are three search providers, Platsbanken's `publication_date` trusted beside the two named. **The tracker schema is taken from jobhunt-hq (MIT).** `applications` with status in `saved, applied, screen, technical, onsite, offer, rejected, withdrawn`, `next_action`, `next_date`, and an append-only `application_events` written by the store on every status entered. The events table is what "days to first screen" and conversion by source are computed from. **`subscriptions` names its labels `company` and `board`.** newsdesk's `outlet` and `section` are news words; roledesk has no rows to migrate, so it uses its own names from the first migration. ## Ingestion **Closure is decided from `self.state`, not from what a `pull_batch` job returns.** The `ats` plugin stamps each board it parses without raising with the run's marker, the ids it saw and whether they are the whole board, and the pull's settle closes a board only when its stamp matches the marker its own batches carried and the read was complete. So a batch that raises part way still closes the boards it finished, and a board no batch reached stays open instead of being closed on an empty id list. **One pull runs at a time, claimed in the database.** The schedule, the Run button and `app job pull`, which drains a queue of its own in another process, could each start a pull while one was fetching; the second overwrote the stored run marker, so the first run's boards failed their stamp check and stayed open, or a settle closed on the other run's id lists, and with extract on two cascades could send the same roles to the model twice. `claim_run` sets `pull:run` to a new marker in one conditional statement, only while it equals `pull:settled` or is older than an hour, so of two starters in two processes one wins; the settle writes `pull:settled` when it ends. A refused `pull` job queues no stage and says "a pull is already running" in its result and a notice, and the CLI prints the same and exits 1. The marker travels in every batch's payload, the plugins stamp with the marker they were handed, and the settle reads its marker off its own batches' payloads, which a batch that raised still has. The hour is the escape for a run that died: a killed process or a killed cascade never settles, and blocking every pull until someone clears a key would be worse than one duplicated fetch after an hour. The guard lives in `app` because `pipeline`'s queue dedups a job against a live job of its kind, not a cascade against a live cascade, and `solo=True` on the `pull` job would not help, since that job ends in milliseconds once it has asked for the chain. **Boards follow companies; searches find them.** `ats` only reads companies someone listed, so it cannot surface a role at a company nobody knew of, and the seed list came from a US-centred project: of 29,000 open roles, 31 were in Denmark. The `search` plugin runs saved queries on boards that span companies, as `search` subscriptions whose `params` are the query, and pulls them in the same task as the boards. **The seed is a list of companies, not of boards.** The first seed was jobhunt-hq's 186 US boards, chosen because they could be read, and 31 of their 29,000 roles were in Denmark. The second is 362 European employers picked by hand, with `board` filled by `app.jobs.discover` from each company's own careers site and checked once by fetching it; 175 have one. The rest stay in the list with the `ats` host their site runs on, so that "cannot read yet" is a filter on the Companies section rather than a company that was never written down, and the next parser to write is whichever host that filter shows most. Teamtailor is first, on this list. A re-run attaches the board an entry names to a row that never had one, so a seed update that gains boards reaches an existing database; it never replaces a board, including a detached one, and never touches affinity, notes or status. Its boards go through `set_board` without the fetch, since they were read when the seed was written and `app companies check` finds the ones that died since. The count of 175 is out of date: the seed has 286 boards, as the paragraph on the seed's gap below says. **`discover` reads the site before it guesses.** A careers page that links its board is the authority, so the home page, its own careers links, then the usual paths are read for a link into a known host, and a page's own "open positions" link one level down. Only when no page names a host are Greenhouse, Lever, Ashby, SmartRecruiters, Recruitee and Personio probed with the company's slug, because a board drawn by a script leaves no link. A probe hit on a common name can be another tenant (`recruitee:google` exists, and is not Google), which is why the seed's boards were fetched and read before they landed, and why `discover --add` reports the roles it found. For the same reason a page that names only an unreadable host ends discovery with that host: probing anyway, as the first version did, could replace a known Workday site with a stranger's Greenhouse board. **A company row carries `ats`, `ats_slug`, `country` and `city`.** `ats` is what discovery found whether or not the app reads it; a company with an `ats` and no board subscription is one it cannot read yet. `ats_slug` is the name that host knows the company by (the `acme` of `acme.teamtailor.com`), so the parser written later has its targets without a second discovery run; with a board it is the board's slug. `country` and `city` come from the seed for now and are the first of the company facts the feed will filter by; funding, size and industry come from a source that has them, not from a column filled by hand. **An employer known only from a search gets a company row when it is first judged, and the Companies list derives that it is one.** Jobindex and Adzuna roles carry a `company_key` with no row in `companies` (67 keys with open roles on the live data of 2026-09-29), so they could not be hidden or liked. `Store.set_affinity` now creates a row for a key that has roles, named by the name its roles give most often, with nothing else set, and the reader draws the control for any role with a `company_key`. Such a row has no board, `ats` or `careers_url`, which the Companies list read as "board not found" and put under "Not readable yet". The rule: a company with no `ats` subscription (not even a detached one) and no `ats`, `careers_url` or `domain` is from job boards (`from_search` on `/api/companies`), labelled so and left out of that filter. Derived rather than a column, because every way of following a company writes one of those (the seed and discover a domain, Follow and `set-board` a board, which detaching hides but keeps), and a search-only company that later gets a domain or a board is followed from then on without a flag to flip. **Jobindex and Adzuna first, not Jooble.** Jobindex, Denmark's largest board, has an RSS twin for every search page, with phrase and required-word syntax and a region id; no key. Adzuna has a documented API with a free key for the UK and most of the EU, but no Denmark. Jooble gives a key only on a manual application and answered a Cloudflare challenge. LinkedIn and Indeed have no public search API. Jobnet was left out at first because its search answered 401; see the next paragraph. **freehire, Jobnet and Akademikernes Jobbank are the fourth to sixth search providers (2026-10-03).** They came from comparing roledesk with github.com/MadsLorentzen/ai-job-search, which reads them. freehire.me is a public JSON API over about 50 hosts (no key, 300 requests a minute, robots.txt invites API use) whose search carries the full text; most of its Danish rows are employers roledesk does not follow, and a copy of a board role folds into the board's by the dupes rule, which now treats every `readers.PROVIDERS` name as a search host. Its query is an OR of words over title, company, text and place, so a search is narrowed by country. Jobnet's `/bff/FindJob/Search` answers 401 without the header `x-csrf: 1` and 200 with it, no login; it has no robots.txt and carries the full text. Jobbank is an RSS feed per search with the text on each ad's page as JSON-LD, so it is the first search reader with `detail`: fetch text and the Fetch button read a search role's page through the board path (`plugins.ats.reader_of`), with the same bar, budgets and per-role state, and `Store.enrich_waiting` hands over search roles too. Its robots.txt allows `/job/` and disallows `/fwd/webjob/`, which is never followed. On a copy of the live data, a first page of each gave 266 roles, of which 20 were copies of roles already read. Jobdanmark is left out: about a quarter of its ads are on Jobnet, freehire carries the rest, and its listing has no text. LinkedIn's guest endpoints are left out: robots.txt disallows `/` for every agent and the terms forbid automated access. **Platsbanken is the third search provider, for Sweden.** The JobTech API (`jobsearch.api.jobtechdev.se/search`) needs no key, states a total, so completeness follows Adzuna's rule, and filters by the taxonomy id of a län (`platsbanken.REGIONS`; Skåne is `CaRE_1nn_cSU`). It refuses an offset above 2000, which the page limit never reaches. The ads carry no usable remote field, so `remote` is read off the headline. Free text ranks by all words rather than requiring them; a quoted phrase narrows it. **A search closes a role only when it listed everything.** A search result is not a complete list, so a role missing from one run has not closed. An Adzuna search listed everything when it read as many distinct results as the `count` it states; a Jobindex search, whose feed states no count, when a page within its page limit came back with fewer than 20 items, counted before the parser drops any, so one malformed item does not pass for the end. Such a search closes like a board; the rest close once no search has listed them for 21 days. A Jobindex answer with no RSS channel raises instead of reading as an empty, complete search. A role two searches found belongs to the last one that listed it, so one search never closes a role the other still lists. Jobindex has since been declared `complete="never"` (its feed states no total), so a Jobindex search closes its roles only by the 21 days and the short-page rule above no longer applies to it. **Jobindex ads are read from the feed, not followed to the employer.** Each item links to Jobindex's own page, and its `/c?t=` redirect leads to the employer's site or ATS. Following it per role would count as a click in Jobindex's statistics and costs a request per role, so discovering a company's ATS board from a search result is left for later. The on-demand fetch (A search role's posting text is fetched on demand, below) does follow the "Se jobbet" link to the posting, for a role somebody opened; the pull still never does. **Switching a board or search off closes its open roles.** Only a pull that reads a target closes its roles, so a target no longer read would keep them open for good. Switched back on, the next pull reopens what it still lists. A batch already in flight when the switch happens reopens them again, so the pull's settle closes every switched-off target once more. **A destructive switch asks first; a reopening one queues a pull instead of waiting for the schedule.** Switching a company's board or a job board search off, replacing a company's board (the Follow form and the row's Set board/Change editor, both `set_board`) and detaching one each close open roles in a tap; the page asks first when there are roles to lose, naming the count, a replace also naming the old and the new board, the same as removing a search and deleting an agent already do. Switching a target back on, following a board, setting a board, tagging a company All roles and saving a search used to answer with nothing until the schedule's next pull, up to six hours later; each now queues `pull` right after, in the API route (`/api/sources/{id}/switch`, `/api/companies/{key}/board`, `/api/companies/{key}/all-roles`, `/api/boards`, `/api/searches`) rather than in the page's script, so a script or `app job pull` calling the same endpoint gets what a click gets. `pull`'s own refusal while one is already running (`claim_run`) is not surfaced as an error: the change is read by the run already in flight, or by the very next one either way. **The Sources tab and the CLI share `app.jobs.sources`.** Adding a board or a search and switching one are one function each, called by `app companies`, `app searches` and `/api/sources*`, so the two cannot disagree about what "off" does. A search or board is run once before it is saved, and refused if it does not answer. A search that finds nothing is refused too, since that is usually a typo in the query; a board that lists nothing is kept, since a company between openings is still one to follow. **Every way a company gets a board is `app.jobs.sources.set_board`.** `app companies add|set-board|discover --add|seed`, `/api/boards` and `/api/companies/{key}/board` all call it, so attaching a board to an existing row, replacing one and creating a company are one code path; the seed importer moved out of `app/cli.py` for this. The company row and its subscription change in one transaction (`Store.set_company_board`), so a board another company already has leaves no company row behind. Its host and slug become the row's `ats` and `ats_slug`; other facts only fill empty columns, so a person's or the seed's values survive. **A company has at most one `ats` subscription, rewritten in place.** Replacing a board changes the row's target and closes the old board's open roles, as switching a board off does; detaching switches it off and hides it (`show` 0), which is how a removed search is kept. Deleting the row instead would leave a batch already in flight writing roles against a subscription id that no longer exists, and adding a second row would clash on the label, which is the company's name. A detached board is left out of the Companies and Sources lists, and the next `set_board` reuses the row. **Discovery that finds nothing readable does not detach a board.** `discover --add` on a company that is read from a board and whose site now names only, say, Workday changes nothing and says so. A board that answers is stronger evidence than a page that names no board; `set-board` or Detach is the explicit step. **SmartRecruiters' board list has no description, so its text is read per role by fetch text.** Its `/postings` endpoint gives title, location and department; the text is only on `/postings/{id}`, whose `jobAd.sections` hold `jobDescription`, `qualifications` and `additionalInformation` (joined) and `companyDescription` (left out, the same blurb on every role). Reading it for every role would multiply a board's requests by its roles, so the reader declares `text="detail"` and fetch text reads only the roles in the cut (2026-09-30; 209 open roles had no text before). **The body cap is 96 MB, with one retry for Greenhouse.** openings.go's 8 MB cap was written against arbitrary URLs, while `ats` only fetches a fixed allow-list of seven ATS hosts, and the real run found `?content=true` boards between 9 and 41 MB. A board that still exceeds 96 MB retries once without `?content=true`, trading the description for the listing. The seven hosts became 22 modules, each with its own allow-list of host names; Greenhouse is still the only reader with a fallback feed. **A board request is streamed, with a 30 s read timeout and a 60 s deadline.** `_get` counts the body as it arrives and refuses it at `MAX_BYTES`, where reading `response.content` first held the whole body in memory before the check. httpx's timeouts are per phase, so a board that keeps sending a byte now and then never timed out; the deadline covers the whole request, redirects and body included, and is checked between chunks. openings.go's 10 s read timeout failed `greenhouse:mongodb` and `greenhouse:feedzai` in a pull of 2026-09-28. Measured on 2026-09-29, three runs each of those two and the five Greenhouse boards with the most open roles, with and without `pay_transparency=true` (84 requests, every one a CloudFront miss): a body of up to 10.4 MB arrives in under a second once it starts, and the first byte waited up to 16.6 s, with the three slowest at 16.6, 14.4 and 10.9 s. The flag made no measurable difference; the slow first byte is the origin's, with or without it. A read may wait 30 s, about twice the worst seen, and the deadline is 60 s, which leaves a large board room on a slower link. **Workable's list endpoint has no URL and no text.** The parser was first written to Workable's published role object, since every slug tried in the build answered an empty list; the first populated board (Hugging Face, 2026-09-28) showed the v3 shape instead: `location` an object, `department` a list, a `shortcode` and no URL, and no description. The role page is `apply.workable.com/{slug}/j/{shortcode}/`. The text is on `/api/v2/accounts/{slug}/jobs/{shortcode}` (`description`, `requirements`, `benefits`), read by fetch text for the roles in the cut as for SmartRecruiters; the row keeps the `shortcode` for it, since `source_id` is the numeric id. **Workable and SmartRecruiters are read to the end, and a board closes roles only when it read the total it states.** Workable answers 10 roles a page with a `nextPage` token and SmartRecruiters at most 100 a page by `offset`, and both parsers read page one only, so the settle took page one for the whole board and closed what fell off it: Delivery Hero stated 980 roles and 100 were open. `_paged` follows the pages 0.5 s apart, up to 100 pages, and the plugin stamps `ats:complete` only when the distinct ids read equal `total` or `totalFound`. The count is taken on the raw results, so a row the parser drops does not block closure, and on distinct ids, so a role repeated by a shifted offset does not fake completeness. A 429 after page one ends the read: the roles read are stored and nothing closes, because a partial list is no evidence that the rest closed. A 429 on page one is a failure like any other. The other five hosts answer with the whole board and are complete whenever they parse. Since then there are 22 host modules, not seven; a board over 100 pages is swept across pulls and closes by two finished sweeps (below), and `_paged` is `_runner.read_listing`. **Teamtailor is read from the career site's `jobs.rss`, and a slug with a dot is the site's own host.** The official API needs a key per company; the feed needs none and carries title, link, guid, `pubDate`, the description, `remoteStatus` and locations, department and role in the `tt:` namespace. `teamtailor:acme` reads `acme.teamtailor.com` and `teamtailor:careers.acme.com` that host, since most career sites run on the company's domain. `_allowed_host` allows exactly that host, redirects included, and a slug must be a DNS name whose last label is not a number; beyond that a target may name any host that resolves, the same trust as any board the owner adds. The feed states no total, so it is read by `per_page=50` and `offset` to an empty page, and a page with nothing new ends the read as incomplete. 23 of the 32 seed companies answered on their `careers_url` host on 2026-09-29; the rest list a marketing site there. **A board that fails on every fetch for 21 days closes its roles.** A board whose fetch raised was only logged, so a company that moved ATS kept its roles open for good behind a 404. The `ats` plugin now records `ats:failing:` in `state` with the time of the first failure in a row and the latest reason, and a fetch that answers removes it. Once the first failure is `STALE_DAYS` old, the same window a search role gets, the settle closes the board's roles; the next answer reopens what it lists through `upsert_role`, as for a board switched back on. The record is plugin state rather than a column because the plugin only sees `self.state`. `/api/companies` returns it as `failing_since` and `failing_reason`, the Companies list shows "not answering since", and `app companies check` prints it beside its live result. **A host is a module in `plugins/readers/`, and registers by existing.** `plugins/ats.py` held eight hosts in six parallel tables and `app/jobs/discover.py` three more, so two people adding a host edited the same lines. Each host is now one file that states its name, label, URL patterns, slug check, allowed host names and either a feed and a parser or a pager; `ats.py` and `discover.py` build their tables from the package, ordered by the module's `RANK` so the select and the probes kept their order. The package sits beside `ats.py` and is not `plugins/ats/`, since `desk.sources.registry` globs `plugins/*.py` and the tests patch names on the `ats` module. The contract is the docstring of `plugins/readers/__init__.py`, and a module that breaks it fails the import by name. **A host is handed the fetch.** A module imports `desk` and `._shared` only and receives `get`, which `ats.py` binds to its own `_get` at call time. The allow-list, the redirect rule, the byte cap and the deadline stay in one place, and a test that patches `ats._get` reaches every host. `_get` refuses an IP address, a local or numeric host name and any port but 443 before it asks, because a Teamtailor or SuccessFactors slug is a host name somebody typed. **Per-role text is read by fetch text, for the roles in the cut.** Workday, SuccessFactors, Oracle, Phenom, BambooHR, Jobylon, Rippling and Gem list a role without its text. The pull reads listings only. After scoring, the `fetch_text` stage (called `enrich` until 2026-10-04, renamed because it reads data and calls no model) reads the role pages of roles without text that are in the cut of an enabled agent, 200 per board and 1,000 per run, and only the roles it filled are embedded and scored again. It follows every pull, a saved agent, an affinity change and an All countries or All roles switch, not a vote. A read that brought no text is tried again after `retry_days` (7). `detail` may fill `DETAIL_FIELDS` only, the columns a later pull with an empty listing value leaves alone; title, url, department and `salary_text` come from the listing. Completeness is decided by the listing alone. The pull used to read 200 pages per board in the order roles were found, so a board of 800 roles took four pulls to reach the roles that mattered. Eightfold, SmartRecruiters and Workable list their roles without text too and are read the same way. **robots.txt is decided when a reader is built, not checked at run time.** The builder reads the host's robots.txt, the owner decides per reader whether to read it anyway, and `READS.robots` records the decision and the date. The runtime matcher went with the readers rework. Jobindex is read in full although its robots.txt disallows `sort=`, `page=` and `geoareaid=`; Adzuna's API host disallows `/` for every agent; the owner decided to read its documented API with the account's key anyway, since the rule is aimed at crawlers. It needs a key in the config and has not run live yet. HR Manager's portal disallows everything but the application form; no attached company uses it. The companies once kept off the automatic route by robots.txt (Novonesis, Darktrace, Criteo, Snyk, Bang & Olufsen, Pandora, Terma, Zenegy, Umbraco) stay on the Watchlist with reason `robots` until each is decided. The SuccessFactors reader uses `/search/` and `/job/` only. Since then `hrmanager:teknologisk` (the Danish Technological Institute) has been attached and has 7 open roles, so an attached company does use HR Manager; and Novonesis, Darktrace and Criteo are Workday boards, no longer on the Watchlist. **Every source is a reader module that declares what it can do.** The 22 hosts and the 3 search providers are modules in `plugins/readers/`, each with `READS = Reads(...)`: board or search, whole or paged listing, where the text is (listing, excerpt, detail, none), how completeness is known (stated, end, whole, never), page size and the host's ceiling, the filters it takes per dimension (none, one value a request, many, host ids through `facets`), whether it states one place, several, or one posting per place, which fields it states and whether its date is trusted, a key, a provisional title, whether an unknown slug answers an empty board, and the robots decision. Capabilities were implied by which functions a module had, and the search providers sat outside the contract with their own getter. `problems()` checks the declaration against the functions at import, and `tests/test_readers_contract.py` runs every module against fixtures, so a new reader that drops a place or a teaser fails there. The contract is the docstring of `plugins/readers/__init__.py`; the types are `_contract.py`. **One runner calls every reader.** `plugins/readers/_runner.py` owns the guarded fetch, paging, one request series per filter value unioned by id, completeness, the fallback feed, 429s and failures. `plugins/ats.py` and `plugins/search.py` are thin `Source` classes over it and keep their state prefixes, so no stored key moved. A paged read cut by `MAX_PAGES` saves its cursor and continues on the next pull, without reading page 1 again, so a new role on page 1 waits one sweep; the owner accepted that over reading the head every pull. A host ceiling (Workday 2,000) is not swept; a filter has to get under it. **A board swept across pulls closes a role only when two finished sweeps in a row missed it.** Roles closing above the saved offset between pulls shift later roles back past it, so a finished sweep misses roles that are still open, and the stated-total check can still pass because `seen` holds ids that closed meanwhile. A complete read that finished a sweep is stamped `ats:swept:`; the settle closes the open roles missing now that are also in `ats:missing:`, the ids the previous finished sweep missed, and keeps the rest there. A complete read that was not swept closes as before and clears the record. A role the host closes takes up to two sweeps to close. **The agents set the reach of a pull.** `app/jobs/reach.py` computes it once per pull: the union of the enabled agents' `any` gates on country, town (as its country) and remote, or everything when one agent has none. Fetching has two filters, countries and role types, and a company has an override for each. A company set to **All countries** (`companies.all_countries`, migration 24) is read with the wide reach: the union of the enabled agents' `require` reach, Europe today, and the union of the `any` gates, so the override never reads less than the board would without it. An agent with no `require` gate on place makes the wide reach everywhere. For a company the owner cares about, a role in Freiburg may be open to remote, or worth asking about for Denmark, while Microsoft Germany is not wanted. The overrides are separate from favourite and liked, and global rather than per agent, because they decide what is fetched and fetching is shared. They matter only for a board of 300 roles or more on a host that filters, so a small company is affected once it grows past that. The Companies list states both halves per board, e.g. "follows agents: DK, SE, remote · all roles" or "all countries (Europe) · follows agents' terms: engineer, product, data", or why the board is read whole. Favourite (affinity 2) affects scoring only, where it skips the `any` gates; it used to widen the fetch to its agent's `require` reach, and migration 21 tagged every company that was a favourite of any agent so nothing read before is lost. That tag, first named All roles in `companies.all_roles`, also replaced a board's `{"reach": "all"}` param, which read everywhere: migration 21 tagged those companies and logged each such board, since no everywhere level is left. Migration 24 renamed the tag to All countries and gave its companies (Mistral AI and OpenAI on live) All roles as well, since the owner wanted their every role. A board's `params` override the agents' reach and All countries. Boards under 300 roles, and hosts with a one-country filter over more than 8 countries, are read whole. A board's size (`ats:size:`, with `ats:sizechecked:`) is set once, not by every read: `set_board` sizes a new board with `ats.board_size` (a stated total from one unfiltered page 1, else a whole read), a board with no size is sized in its batch before its reach is chosen, and Recheck on the Companies row, `app companies size ` and `--missing` size it again. Before, a new board had no size and was read whole on its first pull: Infineon read 999 roles worldwide and cut at page 100. A board whose reader cannot filter is sized by its whole read instead of a second request. On 2026-09-30 `--missing` sized 38 boards the old open-role fallback had sized, among them Bosch 4,830, Verisure 3,447, Microsoft 2,345 and NVIDIA at Workday's 2,000. For a Workday or Oracle site, which filters by its own location ids, the Companies line names a country the site does not list and a missing remote option ("follows agents: DK, remote · SE not on this site"), and "nothing asked" when it lists none, where it used to name what was meant to be asked. SmartRecruiters, Eightfold, SuccessFactors, Phenom, Workday and Oracle filter at the source; countries and remote go as separate series, because the hosts intersect two facets. A complete filtered read closes roles outside the filter, except roles with a vote or an application; a filtered read, or one from a host whose unknown slug answers empty, that lists under 10% of the last read with the same filter counts as failed. **A role has a list of places, resolved against a gazetteer.** Readers kept one place of several, joined them, or the host posted a copy per place. A reader now returns every place and never multiplies a row. `places` (city, region, country, continent, with `place_includes` for Øresund across two countries) and `place_aliases` are seeded from the dictionaries that were in code; `role_places` links each place of a role, and an unknown text is listed by `unresolved_places` until an alias links it. The Place filter and the gates join over the tree, which halved their time and dropped the `EU` fallback. Copies of one posting per place, same host, company and title and texts at least 30% alike, fold into one role that keeps each copy's place and link; the rule applies to every host, since the 5,024 such roles came mostly from hosts that do not declare copies. A place text resolves by its own words (`Gazetteer.resolve`), never by the role's stated `country`, which names one country of a multi-place line: `San Francisco; London, UK` with `US` is in Europe through London. The gates and the Place filter read every place of a kept role, a folded copy's included, so OpenAI's San Francisco role with a Dublin copy meets a Europe gate although its `place` and `country` are San Francisco's; its row read "San Francisco +1" until a row led with the place nearest the agent (below). On 2026-10-03 this kept 45 open roles in agent 2's feed that its own places alone would gate. **A role in several cities leads with the one nearest the viewing agent** (`places.Nearness`). Mistral's Forward Deployed role, kept as its Montréal posting with Abu Dhabi, New York and Paris copies, read "Montréal +3" and opened the Montréal page, while for the owner it is a Paris role. A role's places, its copies' included, are ordered in three tiers read off the agent's gates: a place that meets the `any` group (under one of its `country` or `place` values, or a remote part whose area is open to it through `remote_from`, or that meets the scope with a plain `remote` any gate), then a place inside the `require` scope on country, then the rest, a remote part with no stated area among them. The gazetteer holds no coordinates, so within a tier the home stands in for distance: the first value of the first `any` gate on country or place. A place in one of the group's own towns inside the home leads, then one elsewhere in the home, then the host's order; for agent 2 Copenhagen leads "Denmark", Billund and Stockholm. `GET /api/roles` and `GET /api/roles/{uid}` compute it for the agent the feed is viewed as and only for the roles served: the row carries `place_texts`, `lead_place` and `lead_url` (the leading copy's link, '' when the role's own place leads), and `place` is the lead and "+N" as before. The reader's Places list follows the order, and its posting links and the `o` key open `lead_url`. Without an agent the host's order stands. The gates and the dupes rule do not read the order. On the live copy of 2026-10-04 agent 2 sees the Mistral role as "Paris +3" linking the Paris copy, OpenAI's Applied AI Architect as "Dublin, Ireland +1", and 277 of the 279 kept roles with Copenhagen among several places lead with it; the other two lead with a joined line that names København. **A remote role has a remote area: the places a remote hire may live in** (migration 27, `role_remote`, `app/prep/area.py`). On 2026-09-30 the Place field listed "USA (Remote)", "Remote US" and "United States (Remote)" as three towns, and no filter said which of 3,177 remote roles someone in Denmark could take. Those lines came from a few whole-read Greenhouse and Ashby boards (Grafana Labs, Cloudflare, Monzo, Talkdesk), not from an ingest filter. Danish employers barely post remote roles (11 of 1,395 open Danish roles). The remote roles open to Denmark are the roughly 300 scoped to Europe or EMEA and the 210 scoped to anywhere. The area is the first of these that names a place: the model's `remote_where`, the parts of the place texts that say remote ("Germany (Remote)", "Home Based - EMEA"; "Worldwide" or "Global" in such a part is Anywhere), and the role's resolved places lifted to their countries. "Remote" alone names none, so such a role is remote with no stated area. Anywhere is a standalone place with no aliases and nothing under it, so the Place filter and `under` never reach every role through it, and it never counts as a place for a country gate's empty check. Remote lines are no longer suggested as towns. **A remote chip matches by overlap, and Anywhere is in every one.** `remote:country:DK` ("Remote · Denmark") finds a remote role whose area is Denmark or in it, a place Denmark lies in (Europe, Øresund), or Anywhere: the roles a person living in Denmark can take. `remote:country:EU` finds every European remote role, "Germany (Remote)" included. The owner wanted Remote · Denmark to hold the Europe-wide and worldwide roles rather than have a separate "Remote · anywhere" chip, so `remote:anywhere` is a valid token that is never suggested. A remote role with no stated area matches no `remote:` chip. On the live data of 2026-09-30, Remote · Denmark found 499 roles, Sweden 531, Germany 760 and Europe 1,395, and 122 remote roles had no stated area. **An agent's scope is the first line of the Where block, and plain Remote is every remote role within it.** "Only roles in: Europe / these countries / everywhere" reads and writes the agent's `require` gate on country, which was the implicit scope before, and which a company set to All countries is already read within. The token `remote:any` ("Remote", suggested first for "remote") and the agent's `remote: [remote]` any gate both mean every remote role in that scope: a `require` gate on country reads a remote role that has an area through the area alone, so "Home Based - Worldwide", "Germany (Remote)" and "Remote - Europe" meet Europe, and "Remote US" does not. `any` and `prefer` gates on country keep the place reading. The Where block's Remote line is a choice of no, anywhere within the scope (the plain gate, so the live agent loads and saves unchanged), or only when open to someone in a list of countries and regions (`remote_from`, which matches as the chips do). The remote suggestions are kept to the asking agent's scope, so an agent kept to Europe is not offered Remote · United States. This supersedes the "remote within Europe or anywhere" select of the Where block below. **For remote, the model wins, as it does for seniority.** `remote` is `remote_model`, else the host's word, else the place line (prep `VERSION` 3). Black Forest Labs' Freiburg roles are `OnSite` on Ashby while the text offers remote work with an office week a month, and "the board wins" kept them onsite. The prompt says remote when the hire works from home most of the time, even with a regular office week, and hybrid when there are set office days each week. Extract also answers `remote_where`, the names of where a remote hire may live, and a role waits while `remote_where_model` is NULL, so the roles read before are read once more within the agents' existing limits. Migration 27 moved a board role's stored `remote` into `remote_host` where that was empty, since composing `remote` outright would have wiped 1,280 values that an older reader had mapped. "Remote sensing", "remote control" and "remote monitoring" in a title are not remote. **A company has aliases.** `company_aliases` maps a folded name (marks stripped, ø to o, legal form dropped) to a company, so "Orsted" and "Ørsted" are one company without changing `company_key`. `merge_companies` moves roles, subscriptions and ratings. Empty enrichment columns (sector, stage, size band, founded, last funding, source and date) wait for the startupmap.one and The Hub readers. **A list teaser is kept.** A short description in a listing (Phenom, Oracle, Jobylon, Jobindex, Adzuna) is `roles.teaser`, shown and embedded until the full text arrives, when the vector is dropped and the text replaces it. **A description keeps its shape as marked lines.** `_shared.html_text` turns a host's HTML into a line per paragraph, `• ` before a list item and `## ` before a heading (an `

`..`

`, or a paragraph of at most 80 characters set wholly in bold). `strip_html` had flattened a posting into one line, so sections and bullets ran together in the reader. Plain text with marks, not sanitised HTML, is stored because summarise, extract and embed read the same column, and the reader pane escapes each line before drawing it as `

`, `
  • ` or `

    `; a row's excerpt drops the marks. Titles and teasers stay one line through `strip_html`. List readers overwrite the description on every pull, so their roles take the new shape on the next pull; a detail reader reads a role's page once, so its roles read before 2026-09-30 keep the flat text. **Readers scrape; `prep` decides.** A reader hands on the host's own words (`seniority`, `employment`, `remote`, and `country` only when the host states one per role) and does light cleanup only: text from HTML, dates, the places of a role as a list, pay figures. Mapping lived in 25 readers, each spelling its tables its own way, so changing what "Experienced" means touched a plugin. The `prep` stage (`app/prep/`) maps centrally after every pull and every fetch text run. Seniority, employment and remote go through the host's table in `app/prep/hosts/.py` (whole words, or `MATCH` fragments by substring or token), then a shared word map. Country comes from the resolved places (several European countries give `EU`), and the host's country is only a fallback. Places and company aliases are resolved, and copies and duplicates are folded over the whole database. `upsert_role` stores the host words (`*_host` columns, migration 22) and marks the role `prep_due`. When a table changes, its fingerprint makes the next prep map every open role again from the stored words, with no pull. A word no table knows is listed in `unmapped` (`app prep unmapped`, the Sources page). A host's `remote: False` stays unknown rather than onsite, because SmartRecruiters, Ashby, Recruitee and Workable send it for hybrid roles too. **Unmapped places and words are fixed in code, from a list on Sources.** Settings › Sources › Unmapped lists the place texts of open roles no place resolves (`app prep unlinked`, with the countries and companies of their roles) and the host words no table maps. It has no editor: the owner tells Claude what a text is, and the `unmapped` skill in `.claude/skills` says which dictionary or host table takes it. Code rather than `add_place_alias` rows, because a fix then reaches a new database and is reviewed like any other change. The prep fingerprint covers `places.seed()`, so the next prep adds the new places and spellings to the database and maps every open role again. Copy the list puts both lists on the clipboard, or selects them on the page where there is no clipboard. **Fetch terms narrow what every big board sends.** An agent's `fetch_terms` (migration 23) are words a board of 300 or more roles must match, on a host that takes one query per request (SmartRecruiters, SuccessFactors, Workday, Phenom, Eightfold, Oracle), on the narrow and the wide reach alike (2026-10-04; until then only the wide reach of an All countries company took them). A company set to **All roles** (`companies.all_roles`, migration 24) takes no terms on any of its boards, and its roles skip the titles to leave out in scoring. The terms of a pull are the union over the enabled agents; one enabled agent without terms switches them off. The survey of 2026-09-30 found that every host's keyword matches the whole text, so a term cuts less than a title filter would ("engineer" left 1,713 of Bosch's 4,830). One series per term is unioned by id. Over 8 series a wide read drops the place filter and keeps the terms; a narrow read keeps the places, which the agent's fetch gate needs, and drops the terms. A term-filtered read is never the whole board: it writes no size, prunes no per-role state and closes roles by age only, which is accepted because ranking relies on recency, not on closing. A town in a gate is still fetched as its country. **Seniority has three sources.** `seniority_stated` is the host's word mapped by that host's table in `app/prep/hosts/`, `seniority_title` is `seniority.from_title`, and `seniority_model` is `extract`'s verdict; `roles.seniority` is the first of model, stated, title. `extract` reads roles without a model value, every agent's first pick before anyone's second, with the other two as hints it may overrule, since host vocabularies differ and 57% of roles state nothing. `app seniority` shows per host how often the stated level agrees with the model. **No reader is built on a key lifted from a site's script.** Maersk's API, New Work's and Welcome to the Jungle's search index answer only with a key the page's JavaScript carries, which can change without notice and marks an endpoint that is not open. They are on the Watchlist with reason `key`. **A company has one board, and a company inside its owner's board is read by hand.** DFDS has eleven Teamtailor boards by country and is read from the Danish one. Onfido, Tink, Glovo, Cognigy, Contractbook, Signavio and Native Instruments list their roles in Entrust's, Visa's, Delivery Hero's, NICE's, Scrive's, SAP's and inMusic's boards, where no field separates them reliably; they carry reason `group`. **The seed's gap was mostly discovery, not parsers.** A survey of the 155 companies without a board (2026-09-29, every careers site opened) found 49 on a host the app already read: the slug is not the company's name (`BoschGroup`, `jimdo.com`, `workatbackbase`), the board is on a custom domain or on Lever's EU instance (`lever:eu/`), or the careers page refuses a plain request. 43 were attached by hand from the survey, 46 more with the fourteen hosts added that day, and 286 of 362 companies have a board. Discovery keeps a slug's case for a module with `KEEP_CASE`, since Workday's site names, Gem's, Deel's and Rippling's slugs are case-sensitive; SmartRecruiters and Ashby are not, checked live. **`pull` is a job that starts the cascade, on a default schedule of every 6h.** A schedule enqueues a job kind and a cascade is started by one, so the `pull` job only asks for the chain; declared beside it in `app/jobs/cascade.py`, the schedule is a starting point that an edit under Runs overrides for good. `pull` is not also a task, which would draw two buttons under Runs. **Every whole read is guarded.** The 10% guard held only filtered, narrowed and `empty="suspect"` reads, so 206 of 309 boards, holding two thirds of the open board roles, could close every role on one answer that parsed to nothing: a Greenhouse or Lever body whose shape changed is HTTP 200 and zero rows, and the settle took it for a complete read. Now `_runner.read` raises `Suspect` on any read that is not a sweep and lists under `SUSPECT_SHARE` of what the same read listed last time, once that count is at least `SUSPECT_MIN` (10) for a plain read; filtered, narrowed and suspect reads keep their floor of one. The board is then failing with that reason, its roles stay open, and the Companies row says so. A board that really shrank costs a Recheck, which resets the count through `keep_size`, or `STALE_DAYS` of the same answer, after which the read is accepted and the count reset, since by then its roles have closed anyway. **A read that could not ask remote keeps the remote roles it has.** `ask_for` keeps only the dimensions a reader declares, so on SmartRecruiters, Phenom, SuccessFactors and Eightfold the reach "DK, SE, remote" went out as "DK, SE", the read counted as filtered, and the settle closed every remote role outside those countries: 72 on 2026-09-29 and 30 (Philips, Bosch, Coolblue, Delivery Hero), with the line saying "follows agents: DK, SE". Now the listing records `remote_unasked` (`ats:remote_unasked:`), `_close_unlisted` and `_close_swept` spare roles whose `remote` is `remote`, those close when the board has not listed them for `STALE_DAYS`, and the line says "remote not asked on SmartRecruiters". New remote roles on such a board are still not read; reading it whole instead is the owner's call (`open.md`). **A read that asks nothing is not a read.** When an `ids` dimension maps to no host id, `series` used to return nothing, the listing was complete and empty, and the settle closed the board while the line read "site lists none of DK, SE: nothing asked", a fact about the site. The listing is incomplete now, logged at warning, and the line ends "not closing". **Every target is guarded in its batch, and the failing record goes after the stamp.** `ats._board` dropped `ats:failing` before the rows were stored, and a row that failed in `item_of` or `upsert_role` failed the whole `pull_batch` job: that board had neither a stamp nor a record, and the boards after it in the batch, the same ones every pull since batches are ordered, were not read, never closed and never aged. `run_batch` now wraps each target, records the failure under the source's failing key and moves on; a Kill still propagates. The failing key is removed after `stamp`. **Searches share the runner's bookkeeping.** `search.py` logged a failure and moved on, wrote its own `search:ok/complete/ids`, and read through `read_listing` rather than `read`, so it had no guard: a Platsbanken answer with `hits` renamed read as complete and empty and closed the search at once. It now reads through `_runner.read` (no sweep), records `search:failing:` through `record_failure`, stamps through `stamp`, and the search row shows "not answering since" as a board row does; `failing_boards` reads both prefixes and a search failing for `STALE_DAYS` closes its roles. A removed search forgets its record. **The settle speaks.** Its counts went into the job result, which nothing renders: the settle of 2026-09-30 10:06 closed 12,588 roles with one target unanswered and one incomplete, and the Problems log stayed empty. `close_boards` now raises one `pull.settled` notice when something needs a look: every target unanswered (with its failing reason) or read incomplete (boards only, and not one mid-sweep, or the notice would fire every pull), every board that closed more than `CLOSE_NOTICE` (50) roles or more than half of at least `CLOSE_SHARE_MIN` (10) open ones, and the totals. Its result key `failed` is `unanswered`. `run_pull` and `_boards` release the run claim when building the chain raises, so a finder that fails no longer refuses every pull for an hour with "a pull is already running". **Narrowed boards close by age.** A read by fetch terms closed nothing, so a role that left such a board stayed open for good. A complete narrowed read now closes the board's roles it did not list and that were last seen more than `STALE_DAYS` ago, the rule searches have; no agent has terms yet, so this is latent. **Declarations are checked against fixtures.** Of the `READS` traits only `posted`, `filters`, `complete`, `ceiling`, `empty`, `key` and `scope` were read at run time; `pay`, `remote`, `country`, `seniority`, `employment`, `teaser`, `places` and `text` were checked by nothing, so Platsbanken declared `remote="none"` while its rows set it and HR Manager declared `places="one"` and returned none. `tests/test_readers_contract.py` now parses each reader's listing and detail fixtures and asserts every declared field, a missing fixture fails instead of skipping, `places` has `none`, a search module needs `PARAMS` and `clean_params` and its rows `company`, every prep table names a reader and every reader stating words has a table, and `robots` must carry a date and name the paths the reader requests: seven records named a page the reader never asked for. Every host's robots.txt was read again on 2026-09-30; `api.smartrecruiters.com` disallows `/` for every agent but LinkedInBot, which is with the owner. The paths for modules without `READS`, `robots_page` and `ROBOTS_ANY_CASE` are gone, and `discover._UNREADABLE` lost the ten hosts that have modules. ## Ranking **Scoring is per search agent.** A role is scored as `(uid, agent) -> score`, because a role is only good for a given search. Each gate has a mode: `require` becomes a SQL `WHERE`, `prefer` becomes a weighted term in the score. Gated roles keep their row with a reason. `companies.affinity = 2` skips the `any` group, `-1` mutes. **Three decisions per agent: fetch gate, analysis score, final score (2026-10-04).** The one blended score used to pick what the models read and order the feed, and the owner could not tell which rule did what. Now the fetch gate (region, place, role) is a yes or no applied at the host, in scoring, again after extract and in the feed; the analysis score picks the cut the models read; the final score, `(0.6 fit + 0.2 newness + 0.2 affinity + 0.2 taste) / sum`, orders the feed. Everything else, such as seniority, location and pay, is a filter. `docs/architecture.md` is the target design this follows. **The feed shows every role the agent's fetch gate passes, in every order.** Newest first used to show roles the agent rejected, so a change of order changed which roles were shown. With an agent named, every order joins `scores` and hides gated roles unless Show gated is on. **Saved filters are per agent, stored on the server (`saved_filters`, migration 32).** A saved filter is the feed's query string under a name: applied with one click, deleted, never edited, since a change is a new one. They are per agent because an agent's filters change with what it hunts, and on the server so they follow the owner across devices. **Judge scores 0 to 10, summarise reads the top of both orders, a hidden company is never shown (2026-10-04).** A model's 0 to 100 is an estimate with false precision, so skills, experience and career are 0 to 10 and a broken must-have caps career at 4; the CV match stays 0 to 100 (the weighted mean times 10). Migration 33 cleared every judgement so no old number shows on the new scale, and the first judge run reads the whole cut again. Summarise reads the top `summarise_top` (30) of the want order and of the match order, at most 60 per agent, plus liked and saved roles, since both orders are what the owner reads. The feed's Show hidden companies filter is gone: hidden means hidden. **An agent is the group: it holds several prompts, and `fit` is the best prompt's.** A hunt spans several kinds of role (AI and data leadership, customer-facing technical leadership, AI research), and one blended paragraph ranks a role by its distance to the blend. Each prompt is a named text in `agent_prompts` (migration 14, which moved every non-empty `agents.intent` into a prompt named after the agent and dropped the intent columns), embedded on its own and cached under sha1 of model and text, so an edit re-embeds one prompt. A role's fit is the maximum over the prompts of the calibrated cosine, the first prompt winning a tie, and `scores.prompt` names the winner. Votes, liked companies, gates, weights, limits and `taste` stay per agent, so a vote counts for every prompt; a market watch is a second agent with its own. No third level above the agent was added. `POST /api/agents` still takes `intent` when `prompts` is absent. On the live data of 2026-09-29 the embedder separates the three kinds of role but not seniority: an individual contributor's posting on the same subject ranks beside a head's, so seniority has to come from `extract` and a prefer gate, or from votes. **`fit` is the cosine between a role and a prompt of the agent, mapped to a level by constants calibrated per embedding model: `clip((cos - lo) / (hi - lo), 0, 1)`.** `(cos + 1) / 2` spanned only about 0.87 to 0.95 on multilingual-e5-small, so a prefer gate at 0.2 outweighed all of fit. Min-max across the roles an agent scored in the run fixed the spread but made fit a rank: the best role of a poor set got 1, a role's fit and the 0.9 favourite floor's meaning drifted from run to run, and the `limits` bars that bound the paid stages compared an absolute number with a relative one. The constants are `CALIBRATION` in `app/config.py`, keyed by model name, and an entry under `embed.calibration` replaces a model's built-in one; keyed by model, a change of `embed.model` cannot carry another geometry's constants along. A model with none falls back to min-max per run, with gated roles left out of the range, and the log warns once per run. `taste` is mapped the same way with its own pair. The starter agents' prefer weights are 0.05. **multilingual-e5-small's constants are fit 0.75 to 0.88 and taste -0.14 to 0.19, measured on a copy of the live database.** Over 16,841 open roles and five different intents the raw fit cosine pooled to p1 0.7528, p50 0.7989, p99 0.8528, p99.5 0.8595, p99.9 0.8711 and max 0.9031; per intent p1 ranged 0.7456 to 0.7700 and p99.9 0.8413 to 0.8773. `hi` is above every intent's p99.9, so about 5 of the "Copenhagen engineering" agent's 4,156 ungated roles clip to 1; at 0.86 (p99.5) 75 would, and lose their order where it matters most. The span 0.13 is close to the 0.145 min-max span it replaces, so a prefer weight keeps about its old size against fit. The copy had no votes, so taste comes from synthetic ones, 30 liked and 30 passed roles for each of three intents (pooled p1 -0.1404, p50 0.0429, p99.9 0.1924), and should be re-measured once real votes exist. **The cut's defaults are 500 by fit and 150 by CV closeness, each at least 0.6 (2026-10-04).** The old bars, 0.55 for extract and 0.65 for summarise, were measured on the blended score. Migration 32 reset every agent's limits, since a bar on the blended score means nothing on plain fit. Among agent 2's 7,263 roles passing the fetch gate, 2,086 reach fit 0.6, 1,580 reach CV closeness 0.6 and 2,437 either, so for a broad agent the counts stop the lists; the minimum is for a narrow agent, so roles that do not fit are not read to fill the count. **An agent without a prompt that has text has no fit list.** Its cut is the CV list and its liked and saved roles; it feeds no summarise top, and each score run raises one `score.no_intent` notice naming the enabled agents without an intent. The agent still ranks its own list. **The embedding backend is effectively required.** The intent is a CV or a paragraph per agent, and TF-IDF cannot relate "Kubernetes" to "container orchestration". The model is `intfloat/multilingual-e5-small`, not the English-only `all-MiniLM-L6-v2` roledesk started with: the corpus turned European, and on a sample of the live roles (all open Danish-country roles plus a random sample of the rest, language labelled by a stop-word count) against the "Copenhagen engineering" agent's intent, MiniLM separates engineering from non-engineering roles with an AUC of 0.68 overall but only 0.74 restricted to Danish-country roles, where a Danish-country engineering role beats the rest's non-engineering median only 68% of the time; multilingual-e5-small reaches an AUC of 0.70 overall and 1.00 on Danish-country roles, for about 3x the CPU time. A second multilingual candidate, `paraphrase-multilingual-MiniLM-L12-v2`, measured *worse* than plain MiniLM (AUC 0.60) and was dropped. e5 needs its own "query: " / "passage: " prefixes, which `app/jobs/embed.py` adds by matching the model name, not a separate setting. **Summary and tagging are off; `extract` replaces them.** Every profile declares `SummaryPolicy(enabled=False)` and `TaggingPolicy(enabled=False)`. `extract` is a roledesk `ModelTask` on Haiku that turns title and description into the gate columns, and fills only the columns a plugin left empty. Summaries and tags came back as the `summarise` stage and the Summarise button (below); what stays off is desk's own `SummaryPolicy` and `TaggingPolicy`. **A score is the weighted sum over the sum of the weights.** The agent's `fit`, `recency`, `affinity` and `taste` weights form one denominator, so a score stays in 0..1 whatever the weights are. Prefer gates were removed on 2026-10-04 (migration 32 dropped them): hybrid and similar wishes are feed filters, so a role is never judged twice by the score and by a filter. **A gate rejects on evidence, not on absence, and `any` gates are one group.** A require gate used to gate a role whose column was empty ("country unknown"), and extract, which fills that column, is bounded to the roles that rank, so 2,281 of 15,556 open roles were out of reach for good: every board that writes "Remote", "Hybrid" or "Distributed" as its location. Now an empty column neither passes nor fails; the role ranks, extract reads it, and the rescore gates it on what it found. `any` is the third mode: the `any` gates form one group a role must match one of, so "in Denmark, or remote" is two `any` gates, where require alone could only say "and". `remote` is also read off the location line, as `country` is, since Greenhouse puts "Hybrid" there and nowhere else. **A favourite only raises the level; All countries skips the places (2026-10-04).** A favourite used to skip every gate and score at least 0.9, then (2026-09-29) to skip the `any` group, which made affinity both a widening and a ranking. Since 2026-10-04 the widening belongs to the company switches, the same for every agent: All countries skips the place part of the fetch gate (the `any` group) and All roles the role part (fetch terms and `exclude` gates on title). The `require` gates (the region) apply to every role. Affinity adds about 0.05 (liked) or 0.1 (favourite) to both levels of the cut and its weighted share to the final score. **Gates match loosely where the column is free text.** `place` takes the Place filter's tokens on whole folded words, so `Berlin` matches "Berlin, Germany" and `Lund` no longer matches "Billund"; `company` compares company keys, `languages` passes when every required language is a value, `salary_min` is at least the smallest value, and the rest are case-insensitive equality. Each gate is one SQL `CASE` column, so a require gate filters while the gated row keeps every failed gate as its reason. **`exclude` gates titles out by phrase, not by `function`.** Sales titles (Account Executive, Account Director, Client Partner) and individual data engineering ranked high for the owner's agent, since their postings read like the sales engineering and data leadership the prompts describe. `function = sales` could not remove them: the keyword classifier files "Solutions Engineer" and "pre-sales" under sales, so on the data of 2026-09-30 it would also have gated Field CTO, Director Field Engineering, Staff Solutions Engineer and every AI Deployment Strategist in the agent's top 400. The fourth mode, `exclude`, gates a role that matches any of its values, and the gate's `CASE` column returns the position of the first value that matched so the reason names it ("title account executive"). It applies to favourites, which skip only the `any` group. The new `title` field matches a value as whole words of `title_key`, `LIKE '% phrase %'` over the padded key, so `data engineer` gates "Senior MLOps/Data Engineer" and not "Data Engineering Manager", and Forward Deployed Engineer is untouched. The form has a Leave out titles line under Where. Bare `sales` and `vice president` stay off the owner's list, because they would take Sales Engineer and VP roles, and `account manager` stays off because it would take Technical Account Manager. Measured on the agent's 5,089 ranked roles, the list the owner took gated 283, 13 of them in the top 100. **A role with no vector is scored without `fit`.** The fit weight leaves the denominator, so a role `embed` has not reached yet ranks on recency and affinity instead of sinking to the bottom. It is gated as "no vector" only when fit is the only weighted term, and as "no intent vector" when the intent could not be embedded. **Each run replaces an agent's scores.** `replace_scores` deletes and inserts in one transaction, so a role closed or muted since the last run drops out rather than keeping a stale score, and a reader sees one list or the other. **Starter agents are imported once, by a state marker.** newsdesk seeds whenever its table is empty. Here `agents:seeded` in `state` is set after the import, so deleting every agent survives a restart. **`embed` and `score` run in the server process.** newsdesk isolates `embed` in a child process with a timeout. roledesk's run is one bounded pass over open roles, and in-process keeps the embedder replaceable in tests. The cost is torch's memory staying in the server after the first run; isolate it if that becomes the problem. **The pull cascade is `pull → prep → embed → score → fetch_text → prep → embed → score → extract → score → judge → summarise`.** Every stage is always in the chain and a stage that is off (the switch under Runs, else config.yaml) finds nothing, as in newsdesk. The free stages run first: embed and score cost no tokens, and score writes the cut that bounds everything after it. Extract reads the cut, then score runs again so the fetch gate and the cut see the real location and remote area before judge reads anything. Summarise runs last, on the final order. A stage is addressed by its position in the tuple, since `score` is in it three times. Extract reads `on_ingest` only as a stage of a pull, so with `auto` and no model reachable a pull passes it quietly. `CASCADES` in `app/jobs/cascade.py` is the source. **The cut is the one selection for fetch text, extract and judge (2026-10-04).** Per agent, over the roles passing its fetch gate, the cut is the best `cut_fit_top` by fit level at or above `cut_fit_min`, then the best `cut_cv_top` by CV level at or above `cut_cv_min` among the rest, then every role it liked and every saved role (`scores.cut` is `fit`, `cv` or `kept`). A level is the plain fit or CV closeness plus the affinity bonus. Newness and taste are out: a role is read once and pulls run every few hours, and votes come after the read. The two lists are not merged into one number, since they answer different questions (what I want, what I am) and a merged number lets the stronger side crowd the other out. One depth: a second bar inside the cut would defeat its purpose. Without the Where lines only 118 of agent 2's 500 best by fit were roles it could take, so the cut keeps the fetch gate. The cost is mostly a one-off catch-up (about 16 minutes of extract and an hour of judge for 650 roles on the subscription backend); a change to the CV, a prompt or the like texts re-judges the whole cut, which is accepted. A batch dealt named uids finishes them whatever their rank. **`extract_batch` and `summarise_batch` are `isolate=True`, with a timeout.** `context.check()` only runs between the calls `modeltask.one` makes, not inside one, so a call that hangs on either backend was otherwise unkillable short of restarting the server; a process boundary is what lets a Kill, or the timeout itself, actually end it. One call is already bounded at `agent.timeout`, so the deadline is a few calls' worth (30 minutes for extract, 15 for summarise): a batch still running after that is stuck, not slow. The cost: an isolated job's context has no working `stop`, `task` or `fan_out` (see `pipeline/child.py`'s `context_for`), so a refusal or an account-level failure inside a batch can no longer stop the rest of that task's queued siblings, which run on to the same failure instead of being spared it. **A third order, CV match, from a model reading each agent's best roles against its CV (2026-10-03).** Taken from the `/rank` of github.com/MadsLorentzen/ai-job-search, which has a model score a posting against a written profile on five dimensions. Fit compares topics; it cannot tell a step down, years of experience or a stated deal-breaker, which a model reading both texts can. An agent may hold a CV (pasted, or a `.md`/`.txt` file the browser reads into the box), its languages with a level (suggested from the CV by one model call, then edited), and a soft profile of two free texts, "What I like" (`like_text`) and "What I don't like" (`avoid_text`, the column keeps its name), each covering the work, the workplace and situations, with no split into tasks versus environment; the prompts stay what the owner wants. Both texts feed the career score, which the rubric judges against what the person wants (the prompts), what they like and what they do not like, and whether the tasks and the setting would energise them. A deal-breaker is a hard rule and lives in the agent's gates, so the form has no must-haves box; `must_text` stays a column that only the API sets, and the verdicts and the cap below apply whenever it is non-empty. The stage `judge` (after extract and its rescore in the pull, switched under Runs like extract, Haiku by default; since 2026-10-04 it reads the agent's whole cut instead of its own limits) reads the pairs of an enabled agent with a CV, once per `input_key` (a hash of the CV, prompts, both texts and the role's text), and stores skills, experience and career (0 to 100, their rubric bands verbatim), 1 to 3 strengths and gaps in `role_judgements`, which rescoring and closing never touch. The CV match is the weighted mean of the three, with the weights per agent (`cv_skills`, `cv_experience`, `cv_career` in `agents.weights`, default 30, 25, 30) applied when a role is served, so changing them needs no model call. Culture is left out (guessed from ad text) and location too (the gates do it): a must-haves text (set through the API) that names a place makes the model mark location down, so places belong in the Where rules. The model reports facts and code applies the rules: the must-haves text, when set, is read as one must-have per line (leading bullets and numbers dropped), the judge's profile (``, `` and, when set, ``) numbers them M1..Mn, and for each judgement the model answers `musts`, a verdict per must-have, "met", "broken" only when the posting text clearly contradicts it, or "unclear" when the text does not say (never inferred from silence; a must-have the model leaves out counts as unclear). It scores career on its rubric as before and the career is stored as given. The cap is code's: when a role is served, any "broken" verdict makes career count as `min(career, BROKEN_CAP)` with `BROKEN_CAP = 39` (`app.models`), in `cv_score`, in `Store.judgement` (which serves the model's career, `career_capped` and the must-haves with their text) and in `store._cv_sql`, which reads a `broken` count stored beside the verdicts (`role_judgements.musts` and `.broken`, migration 29), so CV match orders by the capped value too. The verdicts store each line's text, so the reader still shows the must-haves a judgement was made against after the text is edited. The judge's `input_key` carries a format version (`judge.FORMAT`, 3) and the likes text (`agents.like_text`, migration 30), so judgements made before the verdicts or the likes existed are made again; until then they serve with the verdicts they have, or none and no cap. The reader shows each must-have with ✓ met, ✗ broken or ? unclear, and career as "39 (capped: breaks a must-have; model said 55)". CV closeness (2026-10-03) is a free, local signal beside the judge, never in its place: the score run cuts the CV into chunks (`embed.cv_chunks`: paragraphs, a longer one cut by line, then sentence, then word, neighbours joined again up to `CV_CHUNK_CHARS` = 1,200 characters, inside e5's 512 tokens), embeds each as a prompt is ("query: " for an e5 model), caches them in `agent_cv_vectors` under sha1 of the model, the chunking version and the CV text, and stores each ungated role's best cosine over the chunks, scaled to 0..1, as `scores.cv_fit` (migration 31). It is no term of the Agent match score. It has its own band, `Calibration.cv`, fit's when a model has none: a CV chunk is longer than a prompt and sits closer to every posting, so on the copy of 2026-10-03 fit's band (0.75, 0.88) clipped 88 of agent 2's 7,270 ungated roles to 1 and the 50 closest tied on posting date; (0.77, 0.90) clips one. The judge then also read the 50 ungated roles closest to the CV that its score list left out; this became the cut's CV list (2026-10-04). On that copy 43 of agent 2's 50 closest roles were outside its 150 best by score, ranked 153 to 2,632 by score (median 831), 20 of them under `judge_min`. CV match puts the judged roles first by `cv_score`, then the others by `cv_fit`, then by score; a row carries `cv_fit`, and under CV match an unjudged row's gutter shows it faint and italic over an empty bar, a dash without one. Their scale is ten postings a run; ours is the top of a ranking that has already scored every role for free. **A posting's languages and deadline, and a flag rather than a score.** Extract reads `languages_required` as objects (language, level on the ladder basic, conversational, professional, fluent, native, and required or plus) and a deadline, from the opening and the closing lines of the text, since both usually sit at the end. Jobnet and Jobbank state a deadline, kept as `deadline_host`; prep composes `deadline` host first. The language flag is computed when a role is served from the posting's languages and the agent's: ⚠ when a required one is missing or its level is above the agent's, ★ when a plus one is the agent's; it never changes a score. Closing soon is the deadline from today to today plus four days, in UTC. ## The pages **Each roledesk tab renders an empty shell; `static/roles.js` fills it and drives every action.** Roles, Applications, Agents and Companies extend the boilerplate's `base.html`; the server renders only select options (from `app.models`, `plugins.ats.FUNCTIONS` and `plugins.ats.HOSTS`, so they cannot drift from what the store and the plugin accept). One code path for "show this" beats a server-rendered first page plus a client re-render after every filter change. Only Roles, Applications and Watchlist are tabs now: Agents and Companies are settings pages, and Companies is a section of Sources (Two tabs and a cog, Watchlist is a third tab and Settings are three sub-tabs, below). **The feed loads whether or not its enhancements do.** `/api/agents` and `/api/companies` only dim hidden companies, draw the affinity control and pick the viewing agent's score order; the init block used to await both before ever calling `loadFeed`, so a slow or failed one left the feed blank for good behind a silent `catch (err) { return; }`. Now the feed's own request goes out alongside them rather than after, agents and companies fill in and redraw what they touch (the rail, the feed's dimming, the reader's affinity slot) whenever they land, and a feed already fetched with no agent known reloads once the real one is. A failed feed fetch of its own gets an empty state with a retry (`state.feedError`) instead of the same silent blank. **`roles(company=, place=)` match a case-insensitive substring of what the board wrote.** The API's company and place fields are free text a person types, not a slug, so "Trade Republic" finds `trade-republic-bank` without knowing the key. Other pages link with them; the rail no longer types them and shows one as a chip to take off. **A place is matched on whole folded words, by a function registered on the connection.** `roles.place_fold` (migration 17) holds `places.fold(place)`: casefolded, marks stripped, `ø` to `o`, `æ` to `ae`, punctuation to spaces, so `Skane` finds `Skåne` and `Kobenhavn` finds `København`. A filter is a token: `country:DK` is the country column, or a line naming the country or one of its cities while the column is empty or `EU`, which finds 1,193 roles against 1,132 on the column alone; `region:skane` is any name or town of a region in `app/places.py`; `place:malmo` is a town with its aliases. Several tokens are joined by OR. A region is up to 161 phrases, and as `LIKE` clauses over 34,538 roles `region:oresund` took 400 ms, twice per feed request. `place_match(place_fold, country, token)`, which `Store._connect` registers, takes 10 to 30 ms. **The regions are a hand-written list.** Skåne, the Capital Region of Denmark, Zealand, Øresund (the two capital regions), Jutland and Funen, each with its names and towns. On the data of 2026-09-29 no Danish or Skåne town with more than one role was missing. A region elsewhere is added to `REGIONS`. **`seniority` is read from the title until extract has read the role.** Extract had never run, so the column was empty on all 33,881 open roles and a seniority filter or gate had nothing to read. `seniority.from_title` matches whole words in English, Danish, Swedish, German and French and gives 43% of open roles a level. "X Manager" is a level only where it clearly names someone who runs a team, since a product or account manager is an individual contributor; intern wins over a boss named in the title. Known mistakes: "VP" is always exec, "Field CTO" and "Chief of Staff" get none, "Account Director" is director. Extract overwrites the title's level, a level a board states wins over both. Since the ladder, `roles.seniority` is the first of the model's level, the host's stated level and the title's, in that order (Seniority has three sources, above), so a stated level no longer wins over the model's. **Seniority is a ladder of rungs with two tracks.** The first vocabulary was one line (intern to exec) and put a Principal below a Team Lead, and a Staff engineer below any manager, while the owner counts a Principal Solutions Engineer as very senior. From `staff` up, each rung pairs an individual contributor's level with a people lead's, as big tech firms grade them: `staff` with `lead` (a team lead) and `manager`, `principal` (also Senior Staff) with `senior_manager` (also Associate Director, AVP), `distinguished` (Senior Principal, Distinguished, Technical Fellow) with `director` (also Head of), then `exec`. `LADDER` in `app/models.py` gives each word its rung and track, and `roles.seniority` stays one column of words, so gates, `extract` and the host tables work on words. `lead` changed meaning: "Tech Lead", "Lead Engineer" and "Marketing Lead" are `staff`, and only a team lead, supervisor or shift lead is `lead`. In a title, a people level wins over a grade on its own rung, and a grade above it lifts it one rung ("Principal Engineering Manager" is `senior_manager`); a slash is "or" ("Senior/Staff Engineer" is `staff`). Principal sits one rung above Staff, although at some firms it is the top individual grade and at others a senior manager's peer. Migration 25 cleared the model levels the split made ambiguous (staff, lead, manager, director), and prep `VERSION` 2 mapped every open role again. On 2026-09-30 that gave, over 19,230 open roles without copies: staff 1,756, principal 535, distinguished 23, lead 222, manager 736, senior_manager 312, director 883, exec 101, none 9,565. **A filter that most roles cannot answer keeps the ones that do not say.** The Seniority filter keeps roles with no level unless its box is unticked, since 57% have none. The Pay filter leaves out roles that state no pay unless its box is ticked, since 87% state none and the filter would otherwise do nothing. `GET /api/roles/facets` counts each level and pay state under the other filters, so the rail shows what a click would add or lose. **The Seniority filter is a range of rungs and a track, not a button per level.** "At least Staff" is a range, and "manager roles only" is the Staff rung on the people track, so From, To and Track (Both, Individual, People) cover what the buttons did. Only a scattered pick such as junior and director is lost. `GET /api/roles` and `/facets` take `level_from`, `level_to` (names in `RUNGS`) and `track`, which `levels_between` turns into the list of words the store filters on. The rungs below Staff have no track and pass either. The facets still count per word; the rail sums them per rung for the track chosen, and names a rung after the track ("Staff / Manager" with both). The page carries `RUNGS` and `LADDER` as JSON, so the words live in `models.py` only. An old `?seniority=` address is ignored. **Company and Place are chips picked from suggestions.** Only a suggestion becomes a chip, so a filter names something the database holds: a company key, a place token. `GET /api/suggest/companies` and `/api/suggest/places` fold what is typed and match word prefixes, computed per request over 743 companies and 5,600 place lines. `app/static/chips.js` is the input, with no dependency; its tests run with `node --test tests/js/*.test.mjs`. **A filter is a history entry, text is not.** Filters used to replace the entry, so back left the page. Now each filter set pushes one and back takes it off: a tag, the period, a chip, a level, a company. The search box and typed text replace, or back would step through a search a letter at a time, and so do the agent and the order. Every pushed entry carries the address it was pushed over, so closing the reader or taking a company off is `history.back()` when the entry under it is that list, and a new entry otherwise. **A company's name is a link that adds the company to the filters on screen.** In a row and in the reader. With one company filtered a strip over the feed names it, counts its roles, links its careers page and carries the affinity control, which is where a company is starred from. After a change the strip waits for the `score_job` the route answers with and reloads the feed. **A muted company is excluded in SQL, before `LIMIT`.** Filtering after `LIMIT` shipped first and showed nothing once Databricks' 884 freshly pulled roles filled the newest 200 rows and Databricks was muted. **`GET /api/roles` serves a row, not a role.** It used to answer `roles.*`, the whole `Role` (`description`, `feed_text`, `raw` and `article_text` included, about 5.5 KB a role on average) for a feed that only ever shows a title, a few badges and an excerpt; a 1000-row restore was several megabytes of text a phone never renders. `Store.roles_page` selects only the fields a row draws (`RoleRow`), with `excerpt` built by `app.models.excerpt` off a `SUBSTR` of `summary` or `description`, never the column whole. Measured on a copy of the live database: a 60-row page went from 392 KiB to 39 KiB and a 1000-row restore from 6.6 MB to 631 KiB, both about a tenth. The reader is unaffected: it already fetched the whole role by uid when it opened one (`GET /api/roles/{uid}`, still the full `Role`); what changed is that the list row it painted from first, before that fetch lands, no longer carries a body to paint with, so the reader now waits on the fetch for the posting text and the original link the same way it always waited for the summary. **A board's limits are words on its row, and a filter.** The readers declare what they cannot deliver and the runner records how a board was read, and none of it reached the Companies list beyond the reach line and "not answering since". `app/jobs/limits.py` turns both into words per board, in a fixed order: `failing`, `read incomplete`, `swept`, `filtered by reach`, `remote not asked`, `narrowed by terms`, `nothing asked`, `size 0`, `over the ceiling`, `text per role` or `no text` or `excerpt only`, `no pay`, `date not trusted`, `without text: N`, `text failed: M`, `read whole`. The row shows them after the size, the Companies filter offers each as an option under Limits, and `board_open` beside the company's count says how many open roles the board itself has, since the company's count includes search roles. The readers list on Sources shows every trait a reader declares. ## The phone **Two tabs and a cog.** `TABS` in `app/web/pages.py` becomes Roles and Applications; the other seven pages (Agents, Companies, Sources, Jobs, Schedules, Messages, Account) move behind a settings cog at `/settings/`, because nine tabs wrapped to three rows on a phone and six of them were setup or system pages. The Watchlist became a third tab and the settings pages became three sub-tabs, both below. **Watchlist is a third tab: the companies the app cannot read, rated yes or no.** The owner goes through the careers pages of such companies by hand and wanted that list one click from Roles rather than behind the cog, so `TABS` has three entries and the phone bar's tabs are tighter. A company is on it when it has no board subscription and is not known from a search only, or when its board is failing: the rule of the Company boards filter "Not readable yet", read from `GET /api/companies`. The rating is `companies.watch` (migration 15: NULL unrated, 1 on the list, 0 not), global and apart from affinity, which is per agent and ranks roles the app does read. `careers_opened_at` is stamped when the careers link is followed, and On the list sorts by it, never opened first, so a round starts with what is overdue. A row rated under Unrated leaves the list at once. On a phone the search field of Roles is left a few letters wide by the third tab, so while it has the focus the tabs and the queue chip step aside. **A company on the Watchlist says why it is there, and can be added, edited and removed on the tab.** `companies.hand_reason` (migration 16) is one of `unread` (readable, no module yet), `robots`, `blocked` (the site answers a program with a challenge), `key`, `group`, `gone` and `added` (by hand or by an import, not looked at); attaching a board clears it. `POST`, `PATCH` and `DELETE /api/companies` and `app companies add`, `edit`, `checked`, `remove` and `by-hand` are what the LinkedIn import will write through. A company with a reason is never "known from a search only", so one added with a name alone is listed. No second table and no `checked_at`: a company has one careers link, and `careers_opened_at` already says when somebody last looked. A careers link somebody typed is kept: discovery and the seed fill it only when empty. A name is changed only while the company has no board, since the subscription is found by the key the name folds to. **Settings are three sub-tabs: Search agents, Sources, Account.** Six sub-tabs were three setup pages and three system pages for two things, what the app ranks by and where roles come from, so each is one page now and Account stays its own. **The old paths' 301s are gone.** `MOVED` answered 301 for the twelve paths above, kept for the few days between the move and this cut, on the assumption that a bookmark should still land. A browser caches a 301 indefinitely, so a path a future page reused would be unreachable through no fault of that page; a one-person app with no outstanding bookmarks does not need to carry that risk. **Sources is one page, one section per plugin.** Job boards are the `search` plugin's queries, company boards are `ats`'s, and the runs that read both end the page with the message log. A source's section says which plugin it is, and following a company, hiding it and switching its board off are one list. The UI says "job board" for what the API and CLI call a search, since "search agent" already means something else. **Search agents are back in the UI as a list.** One person may run several: their own hunt, and one that monitors roles for someone else, each with its own intent and gates. The list has New and Delete; a delete takes the agent's votes, liked companies and scores with it. **Viewing as on Roles is a select, also with one agent.** One enabled agent used to show as its name, since one is not a choice, but the owner looked for the select to switch agent and found it gone after the second agent was switched off. The select lists the enabled agents; an agent that is off has no fresh scores and is left out. **Settings pages sit beside a rail, and Sources shows one section at a time, chosen by the URL fragment.** The company boards list runs to 50 or 60 companies, so Runs at the end of a stacked page was out of reach and jump links still meant scrolling back up. The rail (`settings/_rail.html`, from `SETTINGS` and `SECTIONS` in `app/web/pages.py`) is sticky beside the content, and a strip under the header below 60rem. The fragment rather than a path per section, because a hidden section stays in the DOM, so each section's script runs unchanged. **Runs is the queue's own elements plus a Problems log.** `` and `` draw what is running and when the pull runs next, the app adds only "Run the pull now", disabled while a pull cascade is live, and the message log is the section's last block rather than a section of its own; `#messages` still lands on it. "Run one stage" went because the cascade is the unit of work: a stage run alone is a partial pull whose result the next stage never sees. `app job ` and `POST /api/jobs` keep the per-stage entry points, which is what "Save and score" uses. **Search agents are cards, edited in place.** An agent is defined by what it looks for, so the intent is the card's body and the weights a small line under it; a list of names and weights hid the part that matters. Edit turns that card into the form and New puts a blank one on top, because the new agent sorts first by id and a form at the bottom of the page was out of sight of the card it changed. **Job boards are a list with New, edited in place like the agent cards.** The form used to sit open above the list and Edit filled it, which read as a stray form. It is a `