The judge numbers an agent's must-haves (one per line) and answers met, broken or unclear for each; career is stored as the model gave it and counts as at most BROKEN_CAP when a role is served, in cv_score, Store.judgement and the SQL of Best CV match. Migration 29 adds role_judgements.musts and broken; the judge's input_key carries a format version so earlier judgements are made again. The reader lists the must-haves with their verdicts and the cap. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
103 KiB
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: enrich 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 enrich. 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 enrich reads only the ranked roles (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 enrich for the ranked roles 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:<target> 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 the enrich run, ranked roles first. Workday, SuccessFactors, Oracle, Phenom, BambooHR, Jobylon, Rippling and Gem list a role without its text. The pull reads listings only. After scoring, the enrich stage reads the role pages of roles without text that an enabled agent ranks in its top enrich.top (500) at enrich.min_score (0.5) or more, best score first, 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 and a star change, 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:<target>; the settle closes the open roles missing now that are also in ats:missing:<target>, 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:<target>, with ats:sizechecked:<target>) 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 <key> 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 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:<place> 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 <h1>..<h6>, 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 <h3>, <li> or <p>; 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 enrich run. Seniority, employment and remote go through the host's table in app/prep/hosts/<reader>.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 big boards send across Europe. An agent's fetch_terms (migration 23) are words a big board must match when it is read with the wide reach: a company set to All countries, or a one-country host whose reach was dropped for needing over 8 requests. A company set to All roles (companies.all_roles, migration 24) takes no terms on any of its boards, and will take no category or level filter either. It replaced a board's {"terms": false} param, which migration 24 moved to the board's company. On its own, All roles changes nothing today, since the narrow reach takes no terms; it is kept for the role filters to come. The terms of a pull are the union over the enabled agents; one enabled agent without terms switches them off. The narrow reach takes no terms, because it already leaves at most about 150 roles on any big board. 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). SmartRecruiters, SuccessFactors, Workday, Phenom, Eightfold and Oracle take one term a request, with one series per term unioned by id; over 8 series the place filter goes first, then the terms. A term-filtered read is never the whole board: it writes no size, prunes no per-role state and closes nothing. Category and level filters wait until something maps agent terms to host ids. 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/<site>), 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:<target>), _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:<target> 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.
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 default bars are 0.55 for extract and 0.65 for summarise. On the same data, the Copenhagen agent's ungated roles clearing each bar, min-max then calibrated, were: 0.3: 3,467 and 3,520; 0.4: 1,837 and 2,090; 0.5: 519 and 728; 0.55: 200 and 307; 0.6: 56 and 111; 0.65: 15 and 35. So 0.55 sends about 300 roles to extract and 0.65 about 35 to summarise, which its top 30 trims; the top-N backstops (500 and 30) stay for an agent whose bar admits more. The old defaults, 0.3 and 0.5, admit 3,520 and 728 on the calibrated scale, where only the top N would stop them. An agent keeps the limits stored with it, so one saved under the old defaults keeps 0.3 and 0.5 until it is edited: a migration cannot tell a stored default from a choice.
An agent without a prompt that has text feeds neither model stage. Its scores have no fit term, so they order roles by recency, affinity and prefer gates, and a fresh role of any kind clears a bar. Store._top_scope leaves such an agent out, 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 and affinity weights and every prefer gate's weight form one denominator, so a score stays in 0..1 whatever the weights are.
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 passes the any group, not the require gates, and has no floor. A favourite used to skip every gate and score at least 0.9. Starring is how the owner widens one company's roles beyond the agent's places, and with every gate skipped a starred Databricks brought 471 US roles. With the require gates kept, the owner's agent shows 166 Databricks roles, all in Europe, against 53 unstarred. The floor went with it: over the widened set it put every role of a starred company above all others whatever its fit. The affinity term still lifts them, and with the default weight of 0.2 Databricks held 33 of the top 60 rows on the data of 2026-09-29.
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, affinity and prefer gates 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 → embed → score → extract → score → 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 their score is what bounds the two model stages. Extract reads only what ranks, then score runs again so the gates read what it filled. A stage is addressed by its position in the tuple, since score is in it twice. Extract reads on_ingest only as a stage of a pull, so with auto and no model reachable a pull passes it quietly. Later decisions added prep and enrich: the cascade is pull → prep → embed → score → enrich → prep → embed → score → extract → score → summarise, and CASCADES in app/jobs/cascade.py is the source.
Extract is bounded like summarise: the top roles of each agent, by that agent's own limits. Extract has short answers but would otherwise touch every open role, and the seed boards alone produced 29,000; at Haiku's rates that is tens of dollars for a first pass over roles nobody will look at. Bounded to the ranking, a pull reads a few hundred. extract_top is the backstop (default 500) and extract_min the real stop (default 0.55, about 300 roles for the starter agent): a fixed count stays flat whatever the boards produce, where a percentage would not. The bounds are per agent rather than config, because one agent may be a wide monitoring search that should read a thousand and another a narrow hunt that wants fifty; one global number fits neither. A batch dealt named uids finishes them whatever their rank, so a running batch is not cut short by a rescore.
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, Best 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), an "avoid / drains me" text and a "must-haves and deal-breakers" text; the prompts stay what the owner wants. The stage judge (after summarise in the pull, switched under Runs like extract, Haiku by default) reads the pairs of an enabled agent with a CV within its judge_top and judge_min limits, 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 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 is read as one must-have per line (leading bullets and numbers dropped), the judge's profile 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 Best 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, 2), so judgements made before the verdicts existed are made again; until then they serve with no must-haves 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)". 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/<name>, 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. <desk-jobs> and <desk-schedules> 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 <stage> 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 <template> now: Edit turns the row into the form, New puts a blank one on top, Save and Cancel close it, and one is open at a time.
Where is one question, and a role passes when it matches any of its lines; the other rules sit under Advanced. The first Where block showed the two levels of the gates as they are stored, a required set of countries and then a one-of set, with ISO codes, and the owner could not read it. It asks "Where can the role be?" now: in these countries (by name), in these towns, remote within Europe or anywhere, and a sentence below says what they add up to, the same sentence the card shows. The stored gates did not change: the lines are any gates on country, place and remote, and "within Europe" is a require gate on country holding the Europe list plus the countries line. A require gate on country the block cannot say, such as Denmark and Sweden only, is a row under Other rules, which moved under Advanced above the read-only JSON and opens when the agent has one. Prefer hybrid ranks rather than filters, so it stands apart. Spellings of a town that differ by accents only share one chip, since place matches without case but with accents, and both are stored. A gate the block cannot express whole lands in the rows, so a load and save without edits returns the same gates.
Affinity and votes are per agent. A company hidden for one hunt may be a favourite for another, and a vote says what one agent should learn from, so both carry the agent id, and the Roles tab and the company list ask for one agent's. Without an agent id the API uses the default agent, the enabled one with the lowest id, so the CLI and older callers keep working.
taste is the liked-minus-passed centroid, as in newsdesk. An agent's votes become one vector, the mean of the liked roles' embeddings minus the mean of the passed ones', and a role's taste term is its cosine to that vector, calibrated like fit, weighted beside fit, recency and affinity. It is the one term an agent learns rather than is told, and it costs no model call.
Roles are a feed with a reader, not links out. GET /roles/{uid} renders the feed with its reader open on that role instead of sending the reader to the board, because 29,194 of 29,196 open board roles already have a description averaging 6,300 characters, and a search role's short teaser is worth reading in place before deciding whether to fetch the rest. The figure is of 2026-09-28: hosts that list a role without its text now leave 1,974 of 24,003 open roles without a description on 2026-09-30, until enrich reads them.
Every link built from someone else's data goes through safeUrl. A board, a search result, a discovered careers page and a saved application's url are all free text from outside the app; an http(s) check before it lands in an href is what keeps a stray javascript: link or a bare string typed into a field from being clickable. The reader needed this first, for original_url, so safeUrl moved to app.js beside the app's other shared helpers rather than staying roles.js's own; companies.js (careers_url), sources.js (a search sample's url) and applications.js (application.url) now use the same one.
A vote moves the rank at read time and never hides. Store.roles multiplies the served score by the vote (0.5 passed, 1.2 liked, capped at 1) instead of triggering a rescore, so a vote's effect on Best match shows at once and needs no job. A vote never removes a role from the list either, because a stray tap must stay visible and a single further tap must be able to undo it.
Read state is a column on roles, and a vote stamps it too. read_at sits beside vote, the same shape as newsdesk's items.read_at, so the feed filters and counts by it directly rather than joining a side table on every page load. set_vote stamps it only when it is still NULL, since voting is reading in newsdesk as well; clearing a vote leaves it alone, because taking back an opinion is not un-reading the posting.
A role's buttons run ▼ ● ▲ ★, and saving a role likes it. The order is low to high, so ▲ sits beside ★. A role worth saving is a liked one, so judge.js casts ▲ for the viewing agent after a save that succeeded, unless ▲ is cast already. Unsaving leaves the vote alone, as clearing a vote leaves the read mark. This is done in the page, not in POST /api/applications, because an application belongs to no agent and a vote does. The company control follows the same order, ⊘ ▲ ★.
Tags are a table, written only by summarise. role_tags(uid, tag) follows newsdesk's tags table rather than a JSON array on roles, so tag_counts and the any/all filter are ordinary SQL (GROUP BY, EXISTS) instead of scanning every row's array. summarise already reads the whole posting once per role, so writing 3 to 8 tags alongside the summary costs no extra model call.
Tag filtering runs in SQL before LIMIT, the same as hide_muted. An EXISTS or COUNT(DISTINCT tag) clause in _roles_from keeps the guarantee the muted-company exclusion already established: a filter narrows the rows a page is built from, not the page after it is already built, so a tag matching only older roles is not silently empty on page one.
"Hidden" is the word the UI uses for affinity -1; the code keeps mute and hide_muted. Renaming the columns would touch every reader of agents and companies for no behavioural gain, so only the toggle's title, the filter label and the dimmed row say "hidden" in the UI.
A company affinity change or an agent save queues a score that will see it. POST /api/companies/{key}/affinity and POST /api/score, which the Search agents page calls after a save, answer with the id of that job, and the page waits on it. score is solo, so the queue dedupes a plain request into the live job keyed score; a queued one has not read anything yet and sees the change, but a running one read the old state, and deduping into it reported "Saved and scored" for a score that did not include the save. So a request during a run queues one follow-up with depends_on the running job, after="done" and the key score:after:<id>, which makes ten clicks during one run one extra pass, and a queued follow-up is the answer until it starts. Without a score after it, an affinity change is invisible in Best match until the next 6-hourly pull, and an unmuted company's roles have no score rows until then.
A search role's posting text is fetched on demand, not in the pull. POST /api/roles/{uid}/text (app/jobs/posting.py) fetches it only when the read page asks, because following Jobindex's link for every role during a pull would count as a click in Jobindex's own statistics; one click for a posting somebody actually opened is fair. A Jobindex role's vis-job page is a short ad with a "Se jobbet" link to the posting itself (the employer's site, The Hub, or Jobindex's jobannonce); the fetch keeps that link as roles.posting_url (migration 26, never written by a pull), reads the text from it, and falls back to the vis-job page's own text. The reader's link-out prefers posting_url, so it leads to the full posting once the text was fetched.
Summarising is bounded to the top roles of each agent, by that agent's own limits, and off unless switched on. The pull's summarise stage only considers roles with no summary yet that are in the top summarise_top (default 30) of an enabled agent's scores and at summarise_min (default 0.65, about 35 roles for the starter agent, stricter than extract's since a summary is the long answer), so the cost stays flat whatever the backlog of open roles is. The bounds live on the agent, beside its gates and weights, for the same reason as extract's: a wide monitoring search and a narrow hunt want different depths, and the agent is where the difference is already expressed. Whether the stage runs is the switch under Runs, or summarise.enabled in config.yaml until the switch is used, and both default to off like extract; the read page's Summarise button asks for one role's summary either way.
extract and summarise are switched on the page, and a stored setting beats config.yaml. extract.enabled and summarise.enabled were read at startup and both false, and nothing in the UI said so: an agent's card read "reads 500 at 0.55 · summarises 30 at 0.65" while neither stage had ever run. The state keys stage:extract and stage:summarise ("on" or "off") override the file, stages.stage_on in app/jobs/stages.py is the one function that decides, and the finders of both tasks ask it, so the stage in a pull, app job extract and app job summarise agree; with no key the file applies, so config.yaml is the default for a fresh database and an existing deployment behaves as before until someone uses the switch. It is a stored setting rather than a rewrite of config.yaml because rewriting config.yaml from the app would lose its comments and a restart is what the switch is meant to avoid. The switch is under Runs (GET and PUT /api/stages, app stages), beside "Run the pull now": turning a stage on starts nothing, the next pull runs it. It works with no model reachable and says who would answer, since a pull passes a model stage quietly then. A search agent's card says "extract is off" and links to the switch; its limits stay editable either way, since they are what the stage reads once on. The Summarise button queues summarise_batch for one uid and never asked the switch.
The schedules element's narrow layout is fixed upstream, in ../boilerplate. <desk-schedules> is a shadow root the app cannot lay out from outside, and pipeline/ is a downstream copy refreshed with git archive, so a fix landing only in roledesk would be reverted by the next refresh.
The phone CSS is copied from health and news, not written from scratch. Both apps have already been through several rounds of phone fixes, and the comments in their app.css say what each rule avoids, so adapting their fragments keeps those fixes rather than rediscovering the same edge cases, such as iOS zooming on a 16px input or a card losing width to a side gutter.
Outside the app
Unposted roles and the network stay outside. Their state is inside: an application row with no role_uid, a contact, next_action and next_date, and a company status such as researching or contacted.
LinkedIn enters only as alert mail over IMAP. Scraping it is banned by contract and enforced. The alert mails also carry personalised recommendations no public API exposes.