Docs for the phone plan: tabs table, decisions, plan deleted
README's tabs table now matches two tabs and the settings cog, and mentions the read page, votes, and the Fetch/Summarise buttons. docs/decisions.md gets a new "The phone" section recording each decision the mobile plan made, confirmed against the merged code. docs/mobile-plan.md is deleted per its own package C. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
1 parent
bf8f6885a5
commit
da1a62577a
3 files changed
+42
-159
No files matched your search
@@ -94,6 +94,32 @@ What was decided for roledesk and the one reason for each. The longer reasoning
|
||||
|
||||
**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.
|
||||
|
||||
## The phone
|
||||
|
||||
**Two tabs and a cog.** `TABS` in `app/web/pages.py` becomes Roles and Applications; the other six 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 old paths answer 301 to their new place, query string kept, so a bookmark or a `?agent=` link still lands.
|
||||
|
||||
**One ranking in the UI, while the `agents` table keeps every row.** The owner read "search agent" as something that searches a board, which is what a saved search does, so `/settings/ranking` edits only the first enabled agent and creates one when the table is empty. Code, API, CLI and config keep `agent`, and nothing is migrated.
|
||||
|
||||
**Roles are a feed with a read page, not links out.** `GET /roles/{uid}` renders the posting inside the app 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.
|
||||
|
||||
**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.
|
||||
|
||||
**"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.
|
||||
|
||||
**Companies, following a board and pruning boards by region merge into one settings page.** A company's affinity used to live on Companies while following its board and pruning boards by region lived on Sources, so acting on one company took two tabs; now Companies is one list with the follow form on top and the prune behind a details below it.
|
||||
|
||||
**A company affinity change enqueues `score`.** `POST /api/companies/{key}/affinity` queues the `score` job right after the update, deduped to a live run of the same kind so ten clicks are one pass. Otherwise an affinity change is invisible in Best match 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.
|
||||
|
||||
**A search role's posting text is fetched on demand, not in the pull.** `POST /api/roles/{uid}/text` scrapes `original_url` only when the read page asks for it, because following Jobindex's redirect 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.
|
||||
|
||||
**Summarising is bounded to the top `per_agent` roles of each agent, and off by default.** The pull's `summarise` stage only considers roles with no summary yet that are in the top `summarise.per_agent` (default 30) of an enabled agent's scores, so the cost stays flat whatever the backlog of open roles is. `summarise.enabled: false` matches `extract`'s own default; the read page's Summarise button asks for one role's summary either way.
|
||||
|
||||
**Jobs and Schedules merge into one Pulls sub-tab.** Both named the same thing from two angles, what is running now and when it runs next, so splitting them was two tabs for one job kind.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -1,151 +0,0 @@
|
||||
# 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/ranking` | Ranking | 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.
|
||||
|
||||
## Ranking
|
||||
|
||||
The agents were three named intents, each a ranking of its own, and the owner read "search agent" as something that searches a board, which is what a saved search does. The UI collapses them to one ranking. Code, API, CLI and config keep `agent` and the `agents` table keeps its rows; nothing is migrated.
|
||||
|
||||
`/settings/ranking` edits the first enabled agent, creating one when the table is empty: a paragraph "What you are looking for" (the intent), the three weights, and the gates in a `<details>` "Advanced" holding the JSON editor as today. No New, no list, no Delete. Saving rescores, as now. The starter list in `config.yaml` is cut to one agent, Copenhagen engineering; the other two move to `config.example.yaml` as examples.
|
||||
|
||||
On Roles the order select reads Newest and Best match. When the table holds more than one enabled agent, from the CLI or the config, the select lists them by name instead of Best match, so nothing the CLI can do is lost. The score badge is labelled match.
|
||||
|
||||
## 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); `--bg` darkened 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 cog `flex: 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)` on `main` (health 741, 762).
|
||||
- PWA: `static/manifest.json`, `icon.svg`, `icon-192.png`, `icon-512.png`, `apple-touch-icon.png`, and the head lines from `news\newsdesk\web\templates\index.html` 18-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, match). 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 company affinity control leaves the row: a row judges the role, and the company is judged on the Companies page and the read page.
|
||||
|
||||
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, a judged select (Any, Liked, Unjudged, Passed), show hidden companies, and show gated.
|
||||
|
||||
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 vote never hides a role: a stray tap must be visible and undoable. A vote moves the rank instead, at read time in `Store.roles`: under Best match the order is `s.score * CASE roles.vote WHEN -1 THEN 0.5 WHEN 1 THEN 1.2 ELSE 1 END`, capped at 1, and the served `score` is that adjusted value, so no rescore is needed and the list reflects a vote at once. Under Newest a passed role is dimmed like a hidden company's. The judged filter (`judged=liked|unjudged|passed`) is a `WHERE` on `vote`. Votes as training for `fit` 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 with its ★ ▲ ⊘ control beside it (the one place a company is judged outside the Companies page), 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 agent'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), ⊘ hide (-1). Pressing the pressed one returns to neutral (0); neutral is no button. "Hidden" is the word everywhere the UI shows affinity -1: the toggle's title, the filter ("Show hidden companies" on Roles, "Hidden" in the select here), the dimmed row. The code keeps `mute` and `hide_muted`. 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; hidden keeps reading it but keeps its roles out of the list and 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 Best match 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".
|
||||
|
||||
## Stealing from news
|
||||
|
||||
Where this plan points at news, the agent copies news's CSS and JS fragments and adapts names, rather than writing its own version of the same thing. News has been through several rounds of phone fixes and the comments in its `app.css` (880-897, 906-912, 916-924, 1948-1952) say what each one avoids.
|
||||
|
||||
## 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.html` with the cog; `templates/settings/_tabs.html`; one template per sub-tab, moved from the existing ones. The Ranking page and `ranking.js` as described under Ranking, and the `config.yaml` starter cut to one agent.
|
||||
- Split `static/roles.js` into `roles.js` (feed), `applications.js`, `ranking.js` and `companies.js`. Shared helpers (`count`, `cell`, `debounce`, `affinityControl`) move to `app.js`. Mechanical, behaviour unchanged.
|
||||
- `app.css`: the frame and phone sections above, the PWA files.
|
||||
- `schema.py` and `models.py`: the new columns and `Role` fields 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`: the `TABS` test, 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, judged filter, vote adjustment 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.
|
||||
Reference in new issue
Block a user