Say how a page with no standard is read, and how a site learns from your corrections
Capturing postings says what the fallback reads now (a title line split
only where the page vouches for a part, a salary and a closing date
after the words the page's own language uses) and gains *Sites you
capture from often*: where a correction is remembered, what teaches and
what does not, how a field says it came from a remembered place, how a
place forgets itself and how you forget it. The capture API documents
`hinted` on a preview and that corrections sent with a capture teach
the same way. Writing a plugin says what the fallback source does, that
remembered places go only to Postulo's own sources, and names the two
new names on the surface. Backups says the export carries them.
Refs postulo/postulo#267
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Say how a listing keeps a history of what arrives about it
Listings gains *A listing's history*: what can be added and from whom,
that an entry points at a file rather than keeping a copy, the same
advert captured again added to the history instead of becoming a
second listing, how the application's page shows the history first,
and where else it goes (the export, account deletion, a contact's
data-protection document, mail clients and plugins).
Tracking applications says the listing's entries head an application's
timeline, and that a merge moves them. The API page documents the
`listings:bind` scope, the two calls a mail client uses, a listing's
`events`, and refusals that name more than one scope. Writing a plugin
documents `record_listing_event` and the testing helper that reads a
history back.
Refs postulo/postulo#270
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Say how a capture keeps the page it was read from, and what keeps that page harmless
Capturing postings gains *Keeping the page*: the source and a
rendering, both off until an administrator and then the person switch
them on, where the kept page is, how long it stays and the account's
ceiling. Its two sentences that still called the browser extension
planned now point at the one that exists.
The capture API documents `keep` and the `page` member of a capture,
the `PUT` that sends a rendering with its answers, the three problem
types it adds, the `413` a request too large for the API now gets, and
what the extensions send today. Configuration lists the six settings
and why keeping is off by default; Hardening says why a kept page never
runs as the stranger's code; the metrics page counts kept pages.
Refs postulo/postulo#256
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Say why an application ended, who put it forward, and how two records become one
Tracking applications gains four sections: why an application ended
(the reason, added then or later, and the last stage read from the
timeline), who referred you and the agency it went through, the notice
of possible duplicates, and merging two companies or two contacts, with
what moves, what the kept record takes and what cannot be undone.
Insights gains the widget *Where and why applications end* and the two
tables *By referrer* and *By agency* under *Where they came from*.
Reports lists the four columns the spreadsheet gains, and why the page
and the PDF do not. The API page names the new fields on an
application, `end_reason` on the status call, and the two ids a new
application may carry. Backups says the archive now holds the people
recorded at no company.
Your career record stops pinning the archive's format number, which
#236 and #239 have both moved since #181 wrote it down.
Refs postulo/postulo#239
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recording an offer from the application's page, what it does to the
status, the calendar and the reminders, and the comparison page; the two
read-only API calls in the scope table.
Refs postulo/postulo#237
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Deadlines, closing dates, and reminders that can be changed
The calendar draws four kinds of entry now and the key along the top is
also the filter; the diary file carries deadlines and closing dates as
all-day entries. A listing you are considering can tell you before it
closes, under Settings. A reminder can be put off, edited or deleted,
from its row and from the API — which is the first and only thing the
API deletes, so the scope table says which is which (#238).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Say what a refusal looks like, since it changed shape
*Responses* listed what each status code means and said nothing about
what comes back with it, which was fine while the answer was one key.
Refusals are RFC 9457 problem documents now (postulo/postulo#296), so
the section gains the five members, a worked example, and the five types
that have a name -- with, for each, the thing a client should actually
do about it.
Also said: which member to branch on (`type`), which never to
(`detail`, translated into the account's language), that an unknown
member is to be ignored rather than treated as a surprise, and what
changed in 0.4.0 for a client written against the old shape.
The paragraph pointing at `openapi.json` now says the refusals are
described there too, with a `Problem` schema, since that is the part a
generated client was missing.
Refs postulo/postulo#296
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Say that the schema needs a token, and document the key and the cursor
The capture API page promised that lists take limit and offset and come back as
{"items", "count"}, which GET /captures did not do; it does now, so the page is
true rather than aspirational about it, and says so where it describes the
capture queue.
Three things the page could not have said before. The schema at openapi.json
now wants a live token or a signed-in browser, which is worth saying plainly,
since anybody who had it working without one will see a 401. A capture may
carry an Idempotency-Key, which is the answer to the retry the page already
told people to expect, so it sits with capturing rather than in a corner of its
own. And every list takes updated_since, which needed a section: the ordering
is the whole point of it, the cursor is the updated_at on each row, a plus sign
in a query string is a space unless it is escaped, and a deletion is the one
thing it cannot report.
409 joins the list of what a refusal means.
Refs postulo/postulo#230
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The capture rate limit counts fetches, on the form and on the API alike
POSTULO_CAPTURE_RATE was described as bounding "captures, per account", and until now it
bounded the capture form and nothing else -- so the page that documents the capture API
said nothing about a limit that did not apply to it. It applies now, and what it counts
is the fetch: a capture sent without html spends it, a capture that brings its own page
does not and answers to POSTULO_API_RATE as before. That distinction is the thing a
client author has to know, so it is written where they are reading: in the capture
section, and again beside the other statuses, where 429 was missing entirely.
Refs postulo/postulo#194
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Say how to ask whether a posting has been captured before
POST /captures/known: listings at the address, captures still waiting, and the softer match on title and company.
Refs postulo/postulo#178
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Say how to send several captures from one page, announced once
The optional batch on POST /captures, and that a posting read off a results page is a stub to triage.
Refs postulo/postulo#177
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The capture API: preview a page, and send corrections with a capture
POST /captures/preview, the `data` field on POST /captures, the line
in the list of every call, and the extension showing what was read
before it sends.
Refs postulo/postulo#171
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Document the whole API surface: every call, the machine endpoints, the plugin API
The API named every call, but the scope each needs lived in prose, and
the discard reasons and what /me answers were not written anywhere. It
gains both, and one list of all 39 calls with method, path and scope,
generated from the API's own routers.
/healthz, /metrics and /logs answer machines about the instance and
were only rows in Configuration. Health, metrics and logs says what
each returns, how it is switched on and guarded, the rate limit, the
parameters /logs takes, and every metric with its labels.
The plugin guide was postulo's docs/PLUGINS.md and never reached the
wiki. It is Writing a plugin now, opening with every kind of plugin,
its entry-point group and the interface it satisfies, and carrying a
reference of all 37 names postulo.plugins.api promises -- eight of
which the guide had never named. It also says plainly that a
notifier's Notification, and the client's DestinationRefused, are used
from outside the surface today.
The sidebar gains a Building on it group for the API and the plugin
guide, and the three pages that linked to docs/PLUGINS.md link here.
postulo's tests/test_wiki_surface.py now reads these three pages
against the code.
Refs postulo/postulo#170
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Take the pages over from postulo/wiki, which this repository now replaces
Until now this was a copy of postulo/wiki, refreshed by postulo's
scripts/publish-wiki.sh whenever somebody remembered to run it. The last
time was 5 September (postulo@9645ee1). This brings it to postulo@b6cfb8f7:
- the four pages that never arrived: Accessibility, Hardening, Listings
and Reports;
- the seventeen that had changed since;
- the images, which the script never copied because it copied *.md and
nothing else, so Home has shown its logo and its Buy me a coffee button
broken since the day they were added.
Nothing here was lost: every earlier commit is a publish, and the pages
they left matched postulo/wiki at 9645ee1 exactly.
From here pages are written in this repository and nowhere else.
Refs postulo/postulo#169
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
