From fc1ad7513f2439dc496adcc07f4da54f82c1050f Mon Sep 17 00:00:00 2001 From: Wolf Date: Fri, 25 Sep 2026 14:06:40 +0200 Subject: [PATCH] Plan: roledesk on a phone 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 --- docs/mobile-plan.md | 141 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/mobile-plan.md diff --git a/docs/mobile-plan.md b/docs/mobile-plan.md new file mode 100644 index 0000000..7a5c418 --- /dev/null +++ b/docs/mobile-plan.md @@ -0,0 +1,141 @@ +# 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 `` 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); `--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. + +``, `` and `` 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 `
` 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 `