Two tabs and a cog, settings sub-tabs, news's feed row and reader, votes, paging, on-demand posting text and a bounded summarise stage, Companies and boards merged, forms on top, plain ledes. Work packages for a fan-out. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
14 KiB
Plan: roledesk on a phone
Written 2026-09-25 after the first real run. It is executed as the work packages at the end, each landing as a commit on main. Package C folds what was decided into decisions.md and deletes this file.
Paths to copy from are under C:\Users\Coolkau\code\: news\newsdesk\web\templates\index.html and news\newsdesk\web\static\app.css (the news UI is one page with inline script, so its markup is quoted, not included), health\webapp\templates\ and health\webapp\static\app.css.
What is wrong
- The top bar has nine tabs and wraps to three rows on a phone. Six of them are setup or system pages.
- Every tab opens with a paragraph written for the developer: the Schedules and Jobs ledes name modules, job kinds and config keys.
- Sources clips. Three sections, a five-column table that collapses into a five-cell card per source at phone width, form labels that carry two-line hints so the boxes do not align, and a form narrower than the table above it.
- Roles is a fixed 200-row list with no paging, a wide Save button, a four-letter affinity control (M N L F) on every row, and no way to read a posting inside the app.
- Applications shows a Next column filled with a placeholder the tracker schema came with ("Read the posting and decide").
- Schedules is the queue's
<desk-schedules>element, a seven-column table with no narrow layout. - Companies collapses to one tall card per company at phone width.
- Cards keep a side gutter and rounded corners on a phone, so width is lost on both sides.
Navigation
Two tabs and a cog. TABS in app/web/pages.py becomes Roles and Applications. The cog is a link to /settings, drawn with health's inline SVG (health\webapp\templates\base.html 26-29), current when the path starts with /settings.
/settings is one shell with sub-tabs, in health's pattern: server-rendered links in a _settings_tabs.html include, each active by request.url.path, an underlined row on desktop that wraps into pills at phone width (health\webapp\static\app.css 389-398 and 611-625). No JS.
| Path | Label | Was |
|---|---|---|
/settings/profiles |
Profiles | Agents |
/settings/searches |
Searches | Sources, the searches half |
/settings/companies |
Companies | Companies, plus the company boards and the prune from Sources |
/settings/pulls |
Pulls | Jobs and Schedules |
/settings/messages |
Messages | Messages |
/settings/account |
Account | Account |
Setup first, system after. The old paths (/agents, /companies, /sources, /jobs, /schedules, /messages, /account) redirect with 301, so ?agent= links and bookmarks keep working.
"Profiles" is a label in the UI only. Code, API, CLI and config keep agent. A search agent reads as something that goes and searches a board, which is what a saved search does; a profile is what every pulled role is scored against.
Frame and CSS
Into app/static/app.css, from health unless noted:
@media (max-width: 640px):main { padding: 10px };.card, .filters, .agent-form, .note { margin-inline: -10px; border-radius: 0; border-inline: 0 }(health 629-635);--bgdarkened in light mode so the band between panels shows (health 701-703).- The top bar stays one row: brand kept,
nav { flex: 1 },nav a { flex: 1 1 auto }, the cogflex: 0 0 auto, no wrap (health 584-609). [hidden] { display: none !important }(health 36-37).@media (pointer: coarse): 44px targets,input, select, textarea { font-size: 16px }so iOS does not zoom (news 996-1020).@media (hover: hover)around every hover rule (news 101-109).input, select, textarea { min-width: 0; max-width: 100% }(news 1782).env(safe-area-inset-top)on the header,env(safe-area-inset-bottom)onmain(health 741, 762).- PWA:
static/manifest.json,icon.svg,icon-192.png,icon-512.png,apple-touch-icon.png, and the head lines fromnews\newsdesk\web\templates\index.html18-40. No service worker.
<desk-jobs>, <desk-schedules> and <auth-account> are shadow roots and read only the --desk-jobs-* tokens; the app cannot lay them out. Schedules is fixed upstream, in package B3.
Roles
The row follows news's feed row (index.html 999-1022, app.css 566-638 and 1839-1846): a grid with a bottom rule, no card. Line one is the title, a link to the read page. Line two is company · place · age. Line three is the badges (remote, function, score for the chosen profile). Then a one-line excerpt: the summary when there is one, else the first 160 characters of description. The actions sit on the right: ▲ ● ▼ ★, news's voteButtons and starButton (index.html 1067-1090) with the filled pressed states (app.css 1906-1941). At 640px the actions drop under the text, right-aligned.
The filter bar at phone width is one row: the order select, the search box, and a Filters button that opens a <details> holding company, place, function, remote, new-in, show muted, show gated and show passed.
Paging. GET /api/roles takes offset and returns {"items": [...], "total": n}. The page loads 60 and appends on an IntersectionObserver sentinel with rootMargin: 600px (news 558-610). The count line reads "60 of 1,204 roles". Offset paging is enough for one person; a cursor is the upgrade if a pull lands mid-scroll often enough to notice.
Votes. roles.vote INTEGER (NULL unjudged, else -1, 0, 1) and roles.voted_at. POST /api/roles/{uid}/vote {"value": -1|0|1} sets it, DELETE /api/roles/{uid}/vote clears it, and pressing the stance a role already has clears it (news vote() 2346-2363, optimistic). A role voted -1 is left out of the list unless "show passed" is on, in SQL beside hide_muted so it is excluded before LIMIT. Votes do not enter the score yet; a fit nudge from votes is a later step once there are enough of them.
★ is Save: POST /api/applications as now. Pressing it on a saved role calls DELETE /api/applications/{id}, which removes the application while its status is still saved and answers 409 once it has moved on.
The read page
GET /roles/{uid} renders role.html; role.js fetches GET /api/roles/{uid}. The layout is news's reader (index.html 1400-1601, app.css 329-428): a bar with ▲ ● ▼ ★ and ↗ to original_url, then title, company, place, badges, salary when stated, the summary when there is one, the text, and the link out once more at the end. At phone width the page is edge to edge (news 1794-1807). Back is history.back() when the list opened it, / otherwise.
The text is description for a board role: 29,194 of 29,196 open board roles have one, 6,300 characters on average. A search role has a 240-character teaser and its original_url is Jobindex's own page. For those, POST /api/roles/{uid}/text runs desk.tools.scrape.scrape(original_url) once and stores the plain text in roles.article_text; the page offers "Fetch the posting" when description is under 500 characters and article_text is empty. On demand rather than in the pull, because decisions.md records that following Jobindex's redirect per role counts as a click in its statistics; one click for a posting somebody opened is fair.
Summary. app/jobs/summarise.py is a ModelTask beside extract, writing roles.summary and roles.summarised_at, with a prompt after news\newsdesk\jobs\summarise.py 63-135: about 60 words, what the role is, the stack, where, what it pays if stated, nothing the posting does not say. Off by default like extract (summarise.enabled: false). As a stage of the pull cascade after score, it takes only roles in the top summarise.per_agent (default 30) of an enabled profile's scores that have no summary, so the cost is bounded whatever the backlog. The read page has a Summarise button that enqueues one for that role.
Applications
Rows are title (link to the read page), company, status select, saved-when. The Next column goes and save_role stops writing the placeholder next_action. The model keeps next_action and next_date for the CLI.
Companies
One sub-tab with one row per company: name (link to Roles filtered by it), a board host badge or "from searches", open roles, an on/off switch when it has a board, and three icon toggles: ★ favourite (2), ▲ like (1), ⊘ mute (-1). Pressing the pressed one returns to neutral (0); neutral is no button. A filter box and an affinity or on/off select sit above the list, and "Follow a company" sits on top of the page, above the list, since the list is 186 rows long.
The follow form has a host <select> (Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Recruitee, Personio), a slug input with its hint under it ("the part after the host in the careers URL: boards.greenhouse.io/acme"), and the company name. The page joins host:slug for POST /api/boards.
Prune moves below the list into a <details> titled "Switch off boards with no roles in a region": a region field, Preview, the list, then "Switch off these N boards". Its lede says what it does: a board none of whose open roles is in the region is switched off; a board whose roles name no country is kept.
The lede also says the difference the page shows: off stops reading the board and closes its roles; mute keeps reading it but hides its roles and leaves them unscored.
Backend: POST /api/companies/{key}/affinity enqueues score after the update. The queue dedupes to a live job of the same kind (pipeline/queue.py 360-366), so ten clicks are one run. Today a change in affinity is not seen in a profile's order until the next 6-hourly pull, and an unmuted company's roles have no score rows at all until then, so they are missing from that order entirely.
Searches
"New search" on top, then the list. Labels are one line each; hints go under the input in .hint, not in the label line, so the boxes align. .form-row { display: grid; grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr)); align-items: start }. The form is as wide as the list: drop max-width on .source-form.
Rows follow news's .srow grid (app.css 659-665 and 783-787): name and on/off switch on line one, query · 12 open · DK 10, SE 2 muted on line two, Edit and Remove as small text links (.linky, news 310-314).
Pulls
One page: "Pull now" and what is running (<desk-jobs>), then the schedule (<desk-schedules>). The lede: "Every 6 hours roledesk reads every board and search, then fills in what each posting says, embeds and scores. Change the cadence below." The extract, embed and score buttons go under a <details> "Run one stage".
Copy
Every lede is rewritten for the person using the app: one or two sentences, no module names, no job kinds, no config keys, no file paths. A code identifier appears only as an example the reader types, such as a cadence.
Boilerplate
pipeline/web/static/schedules.js gets a narrow layout upstream in ../boilerplate: below 640px each row is a two-line grid (name and the on toggle; cadence input, next and last), the add row stacks, and the head row is hidden. Then roledesk's copy is refreshed with git archive as pipeline/README.md describes. The lede in schedules.html is roledesk's own.
Work packages
Phase A is one agent, sequential, because everything after it edits the files it moves. Phase B is four agents in parallel, each in its own worktree, owning the files listed and touching nothing else; each merges to main and deletes its branch when its tests pass. Phase C follows B.
Every package runs uv run pytest before it commits, and uv run app serve with the browser at 375px wide to look at what it changed.
A. Frame, settings, split (Opus)
app/web/pages.py:TABS, the settings sub-tab list, the/settings/*routes, the 301 redirects.base.htmlwith the cog;templates/settings/_tabs.html; one template per sub-tab, moved from the existing ones.- Split
static/roles.jsintoroles.js(feed),applications.js,agents.jsandcompanies.js. Shared helpers (count,cell,debounce,affinityControl) move toapp.js. Mechanical, behaviour unchanged. app.css: the frame and phone sections above, the PWA files.schema.pyandmodels.py: the new columns andRolefields in one migration, so B1 and B4 do not both touch the schema:vote,voted_at,summary,summarised_at,article_text,article_at.tests/test_web.py: theTABStest, a smoke test per page and per redirect.
Done when every old path redirects, every page renders, and the tests pass.
B1. Roles feed, read page, votes, applications (Opus)
Owns roles.html, roles.js, role.html and role.js (new), applications.html, applications.js, the roles and applications sections of app.css, the roles and applications routes in api.py, the paging and vote methods in store.py, and their tests. Renders summary and article_text when present and offers the Fetch and Summarise buttons against the routes B4 adds; the route paths above are the contract.
B2. Companies and Searches (Sonnet)
Owns settings/companies.html, settings/searches.html, companies.js, sources.js, the companies and sources routes in api.py (affinity enqueues score), the sources and companies sections of app.css, and their tests.
B3. Pulls, Messages, Account, schedules upstream (Sonnet)
Owns settings/pulls.html, settings/messages.html, settings/account.html, jobs.js, and in ../boilerplate the schedules.js narrow layout, committed there first, then refreshed into roledesk.
B4. Summarise and fetch text (Opus)
Owns app/jobs/summarise.py (new), cascade.py, config.py and config.example.yaml (the summarise: block), the summary and article setters in store.py, the /api/roles/{uid}/text and /api/roles/{uid}/summarise routes in api.py, and their tests. api.py and store.py are shared with B1: B4 adds its routes and methods at the end of the roles section, and whoever merges second rebases.
C. Docs (Sonnet)
README.md (the tabs table, the quick start), decisions.md entries for each decision above, and this file deleted.