@profullstack/agenticjobs 0.1.0

package/docs/openjob.md

@@ -0,0 +1,200 @@
+# OpenJob
+
+A job posting that an agent can read, and that says out loud whether an agent may
+answer it.
+
+Job postings already have a machine-readable format: schema.org `JobPosting`, which
+search engines index and which most boards emit. OpenJob does not replace it. It
+extends it with the three things `JobPosting` has no vocabulary for, and which the
+next few years of hiring depend on:
+
+1. **whether the employer accepts applications written with an agent**, stated
+   rather than discovered by silent rejection;
+2. **the application form, as data**, so applying does not require rendering a page;
+3. **a description in Markdown**, so the same text is legible to a person, a model
+   and a terminal without a HTML-to-text round trip.
+
+## The document
+
+A listing is a JSON object. Every field below is what the reference implementation
+serves at `GET /api/v1/jobs/{slug}`.
+
+```json
+{
+  "id": "b7c3...",
+  "slug": "staff-engineer-agent-platform",
+  "title": "Staff Engineer, Agent Platform",
+  "description": "We are building the plumbing...",
+  "org": {
+    "slug": "example-works",
+    "name": "Example Works",
+    "website": "https://example.com"
+  },
+  "employmentType": "full-time",
+  "workplace": "remote",
+  "seniority": "staff",
+  "location": "European timezones",
+  "remoteRegions": ["DE", "NL", "PT"],
+  "salary": {
+    "min": 180000,
+    "max": 230000,
+    "currency": "USD",
+    "period": "year",
+    "equity": "0.1% - 0.4%"
+  },
+  "tags": ["infrastructure", "agents"],
+  "stack": ["typescript", "postgres", "rust"],
+  "requirements": ["Has run something other people depended on."],
+  "responsibilities": ["Own the execution layer."],
+  "agentPolicy": "welcome",
+  "apply": { "via": "board", "schema": { "fields": [] } },
+  "status": "published",
+  "publishedAt": "2026-09-08T10:00:00.000Z",
+  "expiresAt": null
+}
+```
+
+`description` is Markdown. Not HTML, and not plain text with the formatting removed.
+
+## agentPolicy
+
+The field this format exists for. Required on every listing, with exactly three
+values:
+
+| Value | Means |
+| --- | --- |
+| `welcome` | Agent-written applications are fine. Nothing is asked. |
+| `disclose` | Fine, but say so. The application carries a structured disclosure. |
+| `human-only` | The employer is asking for something a person wrote. |
+
+Three things about it are deliberate.
+
+**It is required.** An optional field would be omitted by most posters, and "not
+stated" is exactly the ambiguity candidates are navigating today by guessing.
+
+**`human-only` is a request, not a control.** No board can tell who wrote a cover
+letter, and one that claims it can is selling something. Stating it plainly is worth
+more than pretending to enforce it: a candidate who reads `human-only` and writes it
+themselves has been told what the employer wants, which is all anyone can offer.
+
+**Disclosure is not evidence against the candidate.** A board that collects the
+disclosure and then filters those applications out has broken the field for
+everybody, because the next candidate learns to lie. `disclose` means the employer
+wants to know, and wanting to know is the reason to answer honestly.
+
+## apply
+
+Three shapes, and only the first is completable without a browser.
+
+```json
+{ "via": "board",  "schema": { "fields": [ ... ] } }
+{ "via": "url",    "url": "https://example.com/careers/123" }
+{ "via": "email",  "email": "jobs@example.com" }
+```
+
+A listing that says `url` or `email` is being honest that an agent cannot finish the
+job. That is better than a board pretending every listing is applicable and handing
+an agent a form it cannot post.
+
+### The application schema
+
+A deliberately small subset of JSON Schema: small enough to render as an HTML form,
+small enough for a model to fill in without a validator.
+
+```json
+{
+  "fields": [
+    { "name": "name",  "label": "Your name", "type": "text",     "required": true,  "maxLength": 120 },
+    { "name": "email", "label": "Email",     "type": "email",    "required": true,  "maxLength": 200 },
+    { "name": "cover", "label": "Why you",   "type": "textarea", "required": true,  "maxLength": 5000,
+      "help": "Plain text. Short is fine." }
+  ]
+}
+```
+
+`type` is one of `text`, `textarea`, `email`, `url`, `select` or `file`. A `select`
+carries `options`.
+
+An implementation publishes the schema at a stable address alongside the endpoint
+that accepts it, so reading and answering are two requests and no guessing:
+
+```
+GET  /api/v1/jobs/{slug}/apply-schema
+POST /api/v1/jobs/{slug}/apply
+```
+
+### The disclosure
+
+Posted alongside the answers:
+
+```json
+{
+  "agent": { "name": "claude-opus-5 via agenticjobs-mcp", "supervised": true }
+}
+```
+
+`supervised` means a person read it before it was sent. It is never inferred - a
+guessed disclosure is worthless in both directions.
+
+### Resumes
+
+A resume travels as Markdown, in the [OpenResume.md](./openresume.md) convention, in
+a `resume` field. Not a file upload, not a URL to a PDF. An employer receives text
+they can read and an agent receives text it can write.
+
+## Mapping onto schema.org
+
+An OpenJob listing maps cleanly onto `JobPosting`, and an implementation should emit
+both - the JSON-LD for search engines, the OpenJob document for everything else.
+
+| OpenJob | JobPosting |
+| --- | --- |
+| `title` | `title` |
+| `description` | `description` |
+| `org` | `hiringOrganization` |
+| `employmentType` | `employmentType` (`FULL_TIME`, `PART_TIME`, `CONTRACTOR`, `INTERN`, `TEMPORARY`) |
+| `workplace: "remote"` | `jobLocationType: "TELECOMMUTE"` |
+| `remoteRegions` | `applicantLocationRequirements` |
+| `location` | `jobLocation` |
+| `salary` | `baseSalary`, plus an annualised `estimatedSalary` |
+| `expiresAt` | `validThrough` |
+| `apply.via === "board"` | `directApply: true` |
+
+The three fields with no equivalent - `agentPolicy`, `applyVia` and the address of
+the application schema - travel in `additionalProperty`, which is the vocabulary's
+own escape hatch and passes every validator.
+
+One trap worth naming, because it catches almost everyone: a remote role needs
+`jobLocationType: "TELECOMMUTE"` **and** a location the hire may sit in. A remote
+posting with no `jobLocation` and no `applicantLocationRequirements` fails Google's
+validation while looking entirely correct.
+
+## Drafts
+
+A listing has a `status`, and `draft` is the interesting one. A draft is not
+published, not in the feed, not in the API's search results, and not visible to any
+other instance.
+
+This is the employer's human control point. An agent can write the listing; a person
+publishes it. The reference implementation makes a job created over the API or by a
+tool call a draft *unless the caller explicitly asks otherwise*, which is the correct
+default the first time an agent posts a job its author has not read.
+
+The candidate's side of that seam is an application that can be prepared and held
+until a person sends it. Both ends of the transaction have one, or the design is
+lopsided.
+
+## Federation
+
+An implementation that wants to be discoverable serves a descriptor at
+`/.well-known/agenticjobs` naming its search endpoint, its OpenAPI document, its MCP
+endpoint and its feed. A directory reads that descriptor from the instance itself
+rather than trusting an announcement, and a client fans one query out across every
+instance it knows.
+
+Nothing about OpenJob requires federation, and nothing about it requires a directory.
+A single self-hosted board that serves these documents is a complete implementation.
+
+## Implementations
+
+- `agenticjobs` - MIT, https://github.com/profullstack/agenticjobs

package/docs/openresume.md

@@ -0,0 +1,143 @@
+# OpenResume.md
+
+A resume is a Markdown file. That is the whole idea.
+
+Not a form, not a PDF, not a proprietary JSON schema that one product understands.
+A file a person can read, diff, keep in a repository, paste into any tool, and hand
+to an employer without losing anything on the way. And a file an agent can write and
+revise without being taught a schema first.
+
+This document describes the convention. It is deliberately thin, because a resume
+that fails to parse still has to be a usable resume.
+
+## The shape
+
+```markdown
+# Ada Lovelace
+
+- **Email**: ada@example.com
+- **Location**: London
+- **Web**: https://example.com
+
+Mathematician, looking for work on machines that do not exist yet.
+
+## Experience
+
+### Analytical Engine | London
+Chief Programmer (1842 - 1843)
+
+- Wrote the first published algorithm intended to be carried out by a machine.
+- Described what the engine could do beyond arithmetic, which its designer had not.
+
+## Skills
+
+- Languages: analytical notation, French
+- Tools: difference engine, correspondence
+
+## Education
+
+### University of London
+Private tuition in mathematics (1840)
+```
+
+## The rules
+
+There are six, and every one of them degrades rather than fails.
+
+**1. One `#` heading, and it is the person's name.** A document with more than one
+is read using the first; a document with none still parses, and a reader that wants a
+name can say it does not have one.
+
+**2. The bullet list directly under the name is the contact block.** Each item is
+`Key: value`, with or without `**bold**` on the key, or a bare `[label](url)`. Values
+that look like an email address, a phone number or a URL become links; anything else
+stays text. Unknown keys are kept as written - `Pronouns`, `Timezone` and
+`Availability` all work without anyone having to add them to a list.
+
+**3. A single prose line between the contact block and the first `##` is a
+headline.** One line. More than one, and only the first is treated that way.
+
+**4. `##` opens a section.** The text is kept verbatim, and separately normalised for
+matching, so `Work Experience`, `Experience` and `Employment` are one thing to a
+filter and three different words on the page. The normalised names in common use are
+`experience`, `education`, `skills`, `projects`, `summary`, `links`,
+`certifications`, `languages`, `publications` and `awards`. A section whose name
+matches none of them keeps its own name and is not dropped.
+
+**5. `###` opens an entry within a section: a job, a degree, a project.** A `|` in
+the heading splits it into a title and a place - `Company | Berlin`. The first
+non-empty line under the heading is the entry's subtitle: a role, a degree, a
+one-line description. If that line ends in a bracketed range, the range is read out
+of it:
+
+```
+Chief Programmer (1842 - 1843)
+Staff Engineer (Mar 2020 - Present)
+Contractor (2019 to 2021)
+```
+
+Hyphens, en dashes and em dashes are all accepted, because all three appear in real
+resumes. `Present`, `Now`, `Current` and `Ongoing` mark a current role. Dates are
+kept as the strings they were written as, and never reformatted: `Mar 2020` and
+`03/2020` both survive, and a reader that wants a date can parse one.
+
+**6. Bullets under an entry are its highlights.** Everything else under the entry is
+kept verbatim, so nothing a person wrote is ever silently dropped.
+
+## What is deliberately absent
+
+**No required fields.** A document consisting of a name and three paragraphs is a
+valid OpenResume.md.
+
+**No date format.** Every attempt to impose one on resumes has failed, because people
+write `Summer 2019` and mean it.
+
+**No schema version.** Readers ignore what they do not recognise. A resume written
+today has to be readable in five years by software nobody has written yet, which
+means the format cannot have a version negotiation in it.
+
+**No structured skills taxonomy.** Skills are the lines people wrote. Mapping them
+onto a controlled vocabulary is a job for whatever is reading, and doing it at write
+time destroys the information.
+
+## Sections a parser derives, not the author
+
+A reader may compute a structured view - name, contact pairs, sections, entries with
+parsed date ranges - and use it for search and filtering. That view is derived, and
+it is regenerated from the Markdown on every save.
+
+**The Markdown is the canonical copy.** If the structured view and the document
+disagree, the document is right. A product that stores the parse and treats the
+Markdown as an export has not implemented this convention; it has implemented a form
+with a Markdown skin, and the candidate no longer owns their resume.
+
+## Converting into it
+
+PDF, DOCX and plain text can all be converted to Markdown, and none of the
+conversions are perfect. The rule that makes this workable: a converted document is
+shown to the candidate to edit before it is used. A conversion nobody checks is a
+conversion nobody should trust.
+
+The `agenticjobs` reference implementation converts `.docx` by reading
+`word/document.xml` directly, and `.pdf` with `pdftotext -layout`. Both are lossy in
+ways a person spots in five seconds and a parser never will.
+
+## Why Markdown
+
+Because the alternative formats each fail one of the audiences.
+
+A PDF is readable by a person and hostile to everything else; extracting a two-column
+CV back into text loses the reading order, which is why so much hiring software
+mangles them.
+
+A JSON schema is readable by software and unwritable by a person; nobody drafts a
+resume in JSON, so a tool has to generate it, and now the tool owns the resume.
+
+Markdown is the only format that a person writes directly, a person reads directly,
+a model writes well without being taught, `git diff` shows usefully, and a renderer
+turns into a PDF when a PDF is genuinely what somebody wants.
+
+## Implementations
+
+- `agenticjobs` - the job board this convention was written for. MIT,
+  https://github.com/profullstack/agenticjobs

package/migrations/0001_init.sql

@@ -0,0 +1,109 @@
+-- The board itself: who posts, what they post, and who applies.
+--
+-- Forward-only. Each file in this directory runs exactly once, in filename
+-- order, inside one transaction, and is never edited afterwards.
+
+create table if not exists organisations (
+  id           uuid primary key default gen_random_uuid(),
+  slug         text not null unique,
+  name         text not null,
+  website      text,
+  logo_url     text,
+  description  text,
+  created_at   timestamptz not null default now()
+);
+
+create table if not exists users (
+  id           uuid primary key default gen_random_uuid(),
+  email        text not null,
+  name         text,
+  is_admin     boolean not null default false,
+  created_at   timestamptz not null default now(),
+  last_seen_at timestamptz
+);
+
+-- Addresses are compared case-insensitively but stored as the person typed
+-- them, so mail to them looks the way they expect.
+create unique index if not exists users_email_key on users (lower(email));
+
+create table if not exists memberships (
+  user_id  uuid not null references users (id) on delete cascade,
+  org_id   uuid not null references organisations (id) on delete cascade,
+  role     text not null default 'owner',
+  created_at timestamptz not null default now(),
+  primary key (user_id, org_id)
+);
+
+create table if not exists jobs (
+  id                uuid primary key default gen_random_uuid(),
+  slug              text not null unique,
+  org_id            uuid not null references organisations (id) on delete cascade,
+  title             text not null,
+  description       text not null default '',
+  employment_type   text not null default 'full-time',
+  workplace         text not null default 'remote',
+  seniority         text,
+  location          text,
+  remote_regions    text[] not null default '{}',
+  salary_min        integer,
+  salary_max        integer,
+  salary_currency   text not null default 'USD',
+  salary_period     text not null default 'year',
+  salary_equity     text,
+  tags              text[] not null default '{}',
+  stack             text[] not null default '{}',
+  requirements      text[] not null default '{}',
+  responsibilities  text[] not null default '{}',
+  agent_policy      text not null default 'disclose',
+  apply_via         text not null default 'board',
+  apply_url         text,
+  apply_email       text,
+  apply_schema      jsonb,
+  status            text not null default 'draft',
+  published_at      timestamptz,
+  expires_at        timestamptz,
+  created_at        timestamptz not null default now(),
+  updated_at        timestamptz not null default now(),
+  search            tsvector
+);
+
+-- The search vector is maintained by a trigger rather than a generated
+-- column: array_to_string is not immutable in every server version, and a
+-- generated column that fails to create takes the whole migration with it.
+create or replace function jobs_search_update() returns trigger as $$
+begin
+  new.search :=
+    setweight(to_tsvector('english', coalesce(new.title, '')), 'A') ||
+    setweight(to_tsvector('english', coalesce(array_to_string(new.tags, ' '), '')), 'B') ||
+    setweight(to_tsvector('english', coalesce(array_to_string(new.stack, ' '), '')), 'B') ||
+    setweight(to_tsvector('english', coalesce(new.description, '')), 'C') ||
+    setweight(to_tsvector('english', coalesce(new.location, '')), 'D');
+  new.updated_at := now();
+  return new;
+end;
+$$ language plpgsql;
+
+drop trigger if exists jobs_search_trigger on jobs;
+create trigger jobs_search_trigger
+  before insert or update on jobs
+  for each row execute function jobs_search_update();
+
+create index if not exists jobs_search_idx on jobs using gin (search);
+create index if not exists jobs_tags_idx on jobs using gin (tags);
+create index if not exists jobs_stack_idx on jobs using gin (stack);
+create index if not exists jobs_org_idx on jobs (org_id);
+-- The list page and every federated search read exactly this order.
+create index if not exists jobs_published_idx
+  on jobs (published_at desc)
+  where status = 'published';
+
+create table if not exists applications (
+  id         uuid primary key default gen_random_uuid(),
+  job_id     uuid not null references jobs (id) on delete cascade,
+  answers    jsonb not null default '{}'::jsonb,
+  agent      jsonb,
+  status     text not null default 'new',
+  created_at timestamptz not null default now()
+);
+
+create index if not exists applications_job_idx on applications (job_id, created_at desc);

package/migrations/0002_auth.sql

@@ -0,0 +1,82 @@
+-- Sessions, magic links, passkeys and the device flow.
+--
+-- Nothing here stores a credential in a form that is useful if the table
+-- leaks: every token is kept as a SHA-256 of the value that was handed out,
+-- so the only copy of the real token is the one on the member's machine.
+
+create table if not exists sessions (
+  id           uuid primary key default gen_random_uuid(),
+  user_id      uuid not null references users (id) on delete cascade,
+  token_hash   text not null unique,
+  -- What the member sees in their session list: "Firefox on Linux", "CLI on
+  -- workstation". A token they cannot recognise is a token they cannot revoke.
+  label        text not null default 'session',
+  -- True for a token minted by the device flow. Such a token is never allowed
+  -- to reach the admin routes, no matter whose account it belongs to.
+  via_token    boolean not null default false,
+  created_at   timestamptz not null default now(),
+  last_used_at timestamptz,
+  expires_at   timestamptz not null
+);
+
+create index if not exists sessions_user_idx on sessions (user_id, created_at desc);
+create index if not exists sessions_expiry_idx on sessions (expires_at);
+
+create table if not exists magic_links (
+  token_hash text primary key,
+  email      text not null,
+  -- Where to send the member once the link is followed. Same-origin paths
+  -- only; validated before it is written, not when it is used.
+  redirect   text,
+  created_at timestamptz not null default now(),
+  expires_at timestamptz not null,
+  used_at    timestamptz
+);
+
+create index if not exists magic_links_email_idx on magic_links (lower(email), created_at desc);
+
+create table if not exists passkeys (
+  id             uuid primary key default gen_random_uuid(),
+  user_id        uuid not null references users (id) on delete cascade,
+  credential_id  text not null unique,
+  public_key     text not null,
+  -- The authenticator's signature counter. A value that goes backwards means
+  -- the credential has been cloned.
+  counter        bigint not null default 0,
+  transports     text[] not null default '{}',
+  label          text not null default 'passkey',
+  created_at     timestamptz not null default now(),
+  last_used_at   timestamptz
+);
+
+create index if not exists passkeys_user_idx on passkeys (user_id);
+
+-- Held between a challenge being issued and the browser answering it. Rows
+-- are short lived and swept on read.
+create table if not exists webauthn_challenges (
+  challenge  text primary key,
+  email      text,
+  user_id    uuid references users (id) on delete cascade,
+  purpose    text not null,
+  created_at timestamptz not null default now(),
+  expires_at timestamptz not null
+);
+
+-- The device flow, for anything without a browser: the CLI, the TUI, MCP.
+create table if not exists device_codes (
+  device_code_hash text primary key,
+  -- Short, typed by a human, so it is generated from an alphabet with no
+  -- characters that look like each other.
+  user_code        text not null unique,
+  label            text not null default 'terminal',
+  status           text not null default 'pending',
+  user_id          uuid references users (id) on delete cascade,
+  -- Set exactly once, when the code is approved, and cleared the first time
+  -- the waiting client collects it.
+  token            text,
+  interval_seconds integer not null default 2,
+  created_at       timestamptz not null default now(),
+  expires_at       timestamptz not null
+);
+
+create index if not exists device_codes_expiry_idx on device_codes (expires_at);

package/migrations/0003_directory.sql

@@ -0,0 +1,27 @@
+-- The directory: which instances exist, and what each of them last said about
+-- itself.
+--
+-- nixamp's stream directory keeps its entries in memory with a TTL, because a
+-- stream that stops should vanish. A job board that goes down for an afternoon
+-- has not stopped existing, and the URLs people bookmarked still have to
+-- resolve, so these rows are durable and `online` is derived from
+-- `checked_at` instead.
+
+create table if not exists instances (
+  id           uuid primary key default gen_random_uuid(),
+  -- The origin, with no path, query or credentials. One row per origin.
+  url          text not null unique,
+  -- The last descriptor the directory successfully fetched from the instance
+  -- itself. Never what an announcement claimed.
+  descriptor   jsonb not null,
+  first_seen_at timestamptz not null default now(),
+  checked_at   timestamptz not null default now(),
+  failures     integer not null default 0,
+  -- An operator can refuse an instance without deleting it, so that it does
+  -- not simply re-announce itself a minute later.
+  blocked      boolean not null default false,
+  blocked_reason text
+);
+
+create index if not exists instances_checked_idx on instances (checked_at desc);
+create index if not exists instances_failures_idx on instances (failures) where blocked = false;

package/migrations/0004_resumes.sql

@@ -0,0 +1,63 @@
+-- Resumes, in Markdown.
+--
+-- The Markdown is the canonical copy. `parsed` is a derived cache of the
+-- OpenResume.md structure and `search` is a derived index; both are rewritten
+-- from `markdown` on every save and neither is ever the thing edited. A
+-- candidate can keep several, because a resume tailored to one job is the
+-- normal case.
+
+create table if not exists resumes (
+  id          uuid primary key default gen_random_uuid(),
+  user_id     uuid not null references users (id) on delete cascade,
+  -- Unique per user, not globally: two people may both have a "backend" one.
+  slug        text not null,
+  title       text not null default 'Resume',
+  markdown    text not null default '',
+  parsed      jsonb,
+  -- private: only the owner. link: anyone with the URL. public: listed.
+  visibility  text not null default 'private',
+  -- Set when the Markdown was converted from an upload, so a bad conversion
+  -- can be redone from the original instead of retyped.
+  source_name text,
+  source_mime text,
+  source_bytes bytea,
+  search      tsvector,
+  created_at  timestamptz not null default now(),
+  updated_at  timestamptz not null default now()
+);
+
+create unique index if not exists resumes_user_slug_key on resumes (user_id, slug);
+create index if not exists resumes_user_idx on resumes (user_id, updated_at desc);
+
+create or replace function resumes_search_update() returns trigger as $$
+begin
+  new.search :=
+    setweight(to_tsvector('english', coalesce(new.title, '')), 'A') ||
+    setweight(to_tsvector('english', coalesce(new.markdown, '')), 'B');
+  new.updated_at := now();
+  return new;
+end;
+$$ language plpgsql;
+
+drop trigger if exists resumes_search_trigger on resumes;
+create trigger resumes_search_trigger
+  before insert or update on resumes
+  for each row execute function resumes_search_update();
+
+create index if not exists resumes_search_idx on resumes using gin (search);
+
+-- An application carries a COPY of the resume, not a reference to it.
+--
+-- A candidate who rewrites their resume next month must not silently rewrite
+-- what an employer already read and replied to, and a resume deleted after an
+-- interview must not blank the application it was sent with.
+alter table applications add column if not exists resume_markdown text;
+alter table applications add column if not exists resume_title text;
+-- Kept only so the candidate's own "where did I send this" list can group
+-- applications by the resume they came from. Nulled by deleting the resume.
+alter table applications add column if not exists resume_id uuid
+  references resumes (id) on delete set null;
+alter table applications add column if not exists user_id uuid
+  references users (id) on delete set null;
+
+create index if not exists applications_user_idx on applications (user_id, created_at desc);

package/migrations/0005_application_drafts.sql

@@ -0,0 +1,20 @@
+-- A human control point on the candidate's side, matching the one employers
+-- already have.
+--
+-- An employer's agent can write a listing, but it lands as a draft and a
+-- person publishes it. Until now a candidate's agent had no equivalent: it
+-- either sent the application or it did not. This adds the same seam. An agent
+-- prepares an application, the candidate reads it and releases it.
+--
+-- A draft is visible only to the candidate who owns it. It is not an
+-- application until it is submitted, so employers never see one, counts never
+-- include one, and the rate limit does not spend on one.
+
+alter table applications add column if not exists submitted_at timestamptz;
+
+-- Everything that already exists was sent, by definition.
+update applications set submitted_at = created_at where submitted_at is null and status <> 'draft';
+
+create index if not exists applications_draft_idx
+  on applications (user_id, created_at desc)
+  where submitted_at is null;