openroles 0.1.0__tar.gz

openroles-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,23 @@
+name: Bug report
+description: Something reads a board wrongly, or fails
+labels: [bug]
+body:
+  - type: input
+    id: target
+    attributes:
+      label: Board
+      description: The ats:token or board URL (a public board, so it is fine to share)
+      placeholder: greenhouse:acme
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what you expected
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: openroles and Python versions
+      placeholder: openroles 0.1.0, Python 3.12

openroles-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

openroles-0.1.0/.github/ISSUE_TEMPLATE/new_ats.yml

@@ -0,0 +1,22 @@
+name: Support another ATS
+description: Ask for (or offer to build) a reader for another applicant tracking system
+labels: [new-ats]
+body:
+  - type: input
+    id: ats
+    attributes:
+      label: Which system
+      placeholder: Workable
+    validations:
+      required: true
+  - type: textarea
+    id: endpoint
+    attributes:
+      label: Its public board endpoint
+      description: The URL a careers page reads its open roles from, and whether it is documented or allowed by robots.txt
+  - type: checkboxes
+    id: help
+    attributes:
+      label: Helping
+      options:
+        - label: I'd like to build it (see CONTRIBUTING.md, "Adding an ATS")

openroles-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## What changed
+
+## How it was checked
+
+<!-- Tests added or updated, and how you checked it against a real board (without pasting that board's data). -->
+
+- [ ] `pytest` and `ruff check .` pass
+- [ ] No runtime dependency added; works on Python 3.9
+- [ ] robots.txt and the request limits are respected

openroles-0.1.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly

openroles-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e . pytest ruff
+      - run: ruff check .
+      - run: pytest -q
+      - name: The CLI and the MCP server start
+        run: |
+          openroles --version
+          echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | openroles mcp | grep -q list_open_roles

openroles-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+# Runs when a GitHub release is published. PyPI trusts this workflow directly
+# (trusted publishing), so no token is stored anywhere.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

openroles-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.venv/

openroles-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-10-15)
+
+First release.
+
+- Greenhouse, Lever (global and EU), Ashby and Workday boards, in one `Job` shape.
+- `detect`: a board from a company name, a board URL or a careers page.
+- CLI (`openroles`), Python API (`openroles.fetch`, `openroles.detect`) and an MCP server
+  (`openroles mcp`) with no dependencies.
+- robots.txt honoured; two requests per host at a time; Workday stops on 429 or 503.

openroles-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+openroles follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+In short: be welcoming, be kind, assume good faith, and keep criticism about the work.
+Harassment of any kind is not tolerated.
+
+To report a problem, contact the maintainer privately through
+[their GitHub profile](https://github.com/aranculleton). Reports are kept confidential,
+and the maintainer will act on them as the Covenant describes.

openroles-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to openroles
+
+Thanks for helping. openroles is small on purpose: four readers, one shape, no
+dependencies. Contributions that keep it that way are very welcome.
+
+## Set up
+
+```bash
+git clone https://github.com/aranculleton/openroles && cd openroles
+python -m venv .venv && . .venv/bin/activate
+pip install -e . pytest ruff
+pytest && ruff check .
+```
+
+The tests never touch the network. Every answer comes from `tests/fixtures/`, through
+the `web` fixture in `tests/conftest.py`.
+
+## What makes a good change
+
+- **Standard library only.** No runtime dependencies, ever. It is the reason people can
+  drop this into anything.
+- **Python 3.9 and up.** CI runs 3.9 to 3.13.
+- **One shape.** Every reader returns `openroles.Job` with the same fields. A field only
+  one ATS has goes into an existing field or not at all; open an issue first if you think
+  the shape needs to change.
+- **Polite, always.** robots.txt is read and obeyed, never worked around. Two requests per
+  host at a time. A board that answers 429 or 503 is left alone. These are not up for
+  trade-offs.
+- **A test for every fix.** The smallest input that showed the bug, as an invented
+  fixture. Never paste a real company's board or a real person's details into a fixture.
+
+## Adding an ATS
+
+The most useful contribution. A new reader is welcome when the system publishes an
+employer's open roles at an endpoint that is either documented as public or allowed by
+its robots.txt. Wanted, if their boards permit it: Workable, Recruitee, Personio,
+Teamtailor, BambooHR, JazzHR, Breezy.
+
+1. Add `src/openroles/providers/<ats>.py` with `fetch(token) -> list[Job]` and
+   `exists(token) -> bool`, and check robots.txt first unless the endpoint is documented
+   as a public API.
+2. Register it in `providers/__init__.py`, `models.ATS`, and `discover.py` (its board URL
+   pattern, so `detect` finds it).
+3. Add an invented fixture and tests: the fields, an unknown board, robots.txt saying no.
+4. Add a row to the README's "Supported systems" table and a line to `CHANGELOG.md`.
+
+## Pull requests
+
+Small and focused is easiest to review. CI must be green (ruff and the tests on every
+supported Python). Say in the description what you changed and how you checked it
+against a real board, without pasting that board's data.
+
+## Releases
+
+Maintainers bump `__version__` in `src/openroles/__init__.py`, add the `CHANGELOG.md`
+entry, and publish a GitHub release. The release workflow builds the package and
+publishes it to PyPI.
+
+## Conduct
+
+Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

openroles-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aran Culleton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openroles-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: openroles
+Version: 0.1.0
+Summary: Every open role, straight from the employer's own ATS: Greenhouse, Lever, Ashby and Workday, with no key and no dependencies. CLI, Python API and MCP server.
+Project-URL: Homepage, https://github.com/aranculleton/openroles
+Project-URL: Issues, https://github.com/aranculleton/openroles/issues
+Project-URL: Changelog, https://github.com/aranculleton/openroles/blob/main/CHANGELOG.md
+Author: Aran Culleton
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ashby,ats,careers,greenhouse,job-board,job-search,jobs,lever,mcp,workday
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Office/Business
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# openroles
+
+**Every open role, straight from the employer's own careers system.** Greenhouse, Lever,
+Ashby and Workday, in one shape, from the same public JSON their own careers pages read.
+No API key, no account, no scraping service, and nothing but the Python standard library.
+
+[![CI](https://github.com/aranculleton/openroles/actions/workflows/ci.yml/badge.svg)](https://github.com/aranculleton/openroles/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/openroles)](https://pypi.org/project/openroles/)
+[![Python](https://img.shields.io/pypi/pyversions/openroles)](https://pypi.org/project/openroles/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+```console
+$ pip install openroles
+$ openroles figma --query data --limit 3
+2026-09-23  Data Engineer Intern (2027)      San Francisco, CA • New York, NY          https://boards.greenhouse.io/figma/jobs/6178851004?gh_jid=6178851004
+2026-09-21  Data Platform Engineer           San Francisco, CA • New York, NY • Unite  https://boards.greenhouse.io/figma/jobs/6201407004?gh_jid=6201407004
+2026-09-21  PhD Intern, Data Science (2027)  San Francisco, CA • New York, NY          https://boards.greenhouse.io/figma/jobs/6200626004?gh_jid=6200626004
+
+3 open role(s)
+```
+
+Give it a company name, a careers page, a board URL or `ats:token`. It finds the board,
+reads every open role, and gives you the same fields whichever system the employer uses.
+
+## Why
+
+Job sites miss roles, show them late, and repost them stale. The employer's own board is
+the source: it is complete, current, and carries the real apply link. Every major
+applicant tracking system publishes that board as JSON for its own careers page.
+`openroles` reads it the same way, politely, and puts the four biggest systems behind
+one function.
+
+## Install
+
+```bash
+pip install openroles          # or: uvx openroles <company>
+```
+
+Python 3.9 or newer. No dependencies.
+
+## Command line
+
+```bash
+openroles linear                                   # every open role at Linear
+openroles https://jobs.ashbyhq.com/linear          # the same, from the board URL
+openroles lever:zoox --query "data" --since 14     # title words, posted in the last 14 days
+openroles figma --location "New York"              # filter by place (--remote for remote only)
+openroles https://adobe.wd5.myworkdayjobs.com/external_experienced \
+          --query "data scientist" --details       # Workday, with each posting's description
+openroles detect "Figma"                           # which ATS, and the board's token
+openroles linear --json > roles.json               # JSON (the default when piped), or --jsonl
+```
+
+## Python
+
+```python
+import openroles
+
+openroles.detect("Figma")
+# [Board(ats='greenhouse', token='figma'), Board(ats='ashby', token='figma')]
+
+jobs = openroles.fetch("greenhouse:figma", query="data", location="New York")
+for job in jobs:
+    print(job.posted, job.title, job.location, job.url)
+
+job.to_dict()   # plain JSON-ready dict
+```
+
+`fetch()` raises `openroles.BoardError` when a board cannot be read (a wrong token, no
+answer), and `openroles.RobotsDisallowed` when the host's robots.txt says no.
+
+## For AI agents (MCP)
+
+`openroles mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over
+stdio, so Claude, Cursor and other agents can look up any employer's open roles
+themselves. Two tools: `find_job_board` and `list_open_roles` (descriptions left out
+unless asked for, to keep answers short).
+
+Claude Code:
+
+```bash
+claude mcp add openroles -- uvx openroles mcp
+```
+
+Claude Desktop, Cursor and other clients (`mcpServers` in their config):
+
+```json
+{
+  "mcpServers": {
+    "openroles": { "command": "uvx", "args": ["openroles", "mcp"] }
+  }
+}
+```
+
+There is also [`llms.txt`](llms.txt), a short brief for a model that has to use the
+library or the CLI.
+
+## What you get
+
+Every role, from every system, has the same fields:
+
+| Field | |
+|---|---|
+| `id` | stable across runs: `gh-`, `lv-`, `ab-` or `wd-` plus the ATS's own id |
+| `ats`, `board` | where it came from, e.g. `greenhouse`, `figma` |
+| `title`, `url` | the role and its apply page |
+| `location`, `locations` | every location the posting lists, joined and as a list |
+| `remote` | `True`, `False`, or `None` when the board does not say |
+| `posted` | `YYYY-MM-DD`, first published (not last edited) where the ATS says |
+| `department`, `employment_type` | where the board provides them |
+| `compensation` | the posted pay band, where the employer publishes one |
+| `deadline` | where the board provides one |
+| `description` | plain text, HTML removed |
+
+## Supported systems
+
+| ATS | Requests | Notes |
+|---|---|---|
+| Greenhouse | 1 per board | descriptions included |
+| Lever | 1 per board | descriptions with their requirement lists; EU boards found automatically |
+| Ashby | 1 per board | descriptions and posted pay included |
+| Workday | 1 per 20 roles, plus 1 per description | `--query` searches the board; `--country` narrows it; `--details` fetches descriptions |
+
+`detect` finds a board from a company name (Greenhouse, Lever and Ashby, by trying the
+names an employer is likely to use), from any board URL, and from a careers page that
+links to or embeds one. A Workday board cannot be guessed from a name: give its URL.
+
+Not supported, because none publishes an open board this way: SuccessFactors, Oracle,
+iCIMS and custom careers sites. SmartRecruiters publishes one, but its robots.txt closes it
+to every crawler except LinkedIn's, so `openroles` does not read it.
+
+## Polite by design
+
+- **robots.txt is read first** for Ashby, Workday and any careers page, and a refusal is
+  honoured, never worked around. For Workday the careers site's own rules count too.
+- **At most two requests in flight per host**, a timeout on every call, and an honest
+  `User-Agent` naming this project.
+- **A Workday board that answers 429 or 503 is left alone** for the rest of the run.
+
+## Is this allowed?
+
+Greenhouse, Lever and Ashby document these endpoints as public job board APIs, for
+exactly this purpose: showing an employer's open roles somewhere else. Workday's is the
+endpoint its own careers pages call; it is not documented, it can change without notice,
+and `openroles` only reads it where robots.txt allows. Use it the way the boards are
+meant to be used: to find roles and apply to them, at a human pace. It is not a tool for
+hammering a site or republishing someone's board wholesale.
+
+## Where it came from
+
+`openroles` is the employer-board reader from
+[last-job-search](https://github.com/aranculleton/last-job-search), a job search that Claude
+runs end to end, extracted so anyone can use it.
+
+## Contributing
+
+Contributions are welcome, and the most useful one is a reader for another ATS
+(Workable, Recruitee, Personio, Teamtailor and more are wanted). [CONTRIBUTING.md](CONTRIBUTING.md)
+has the set-up, the few rules that keep the library small and polite, and a checklist
+for adding a system. Bugs and requests go in [Issues](https://github.com/aranculleton/openroles/issues).
+
+```bash
+pip install -e . pytest ruff
+pytest && ruff check .        # offline: every answer comes from tests/fixtures/
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

openroles-0.1.0/README.md

@@ -0,0 +1,169 @@
+# openroles
+
+**Every open role, straight from the employer's own careers system.** Greenhouse, Lever,
+Ashby and Workday, in one shape, from the same public JSON their own careers pages read.
+No API key, no account, no scraping service, and nothing but the Python standard library.
+
+[![CI](https://github.com/aranculleton/openroles/actions/workflows/ci.yml/badge.svg)](https://github.com/aranculleton/openroles/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/openroles)](https://pypi.org/project/openroles/)
+[![Python](https://img.shields.io/pypi/pyversions/openroles)](https://pypi.org/project/openroles/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+```console
+$ pip install openroles
+$ openroles figma --query data --limit 3
+2026-09-23  Data Engineer Intern (2027)      San Francisco, CA • New York, NY          https://boards.greenhouse.io/figma/jobs/6178851004?gh_jid=6178851004
+2026-09-21  Data Platform Engineer           San Francisco, CA • New York, NY • Unite  https://boards.greenhouse.io/figma/jobs/6201407004?gh_jid=6201407004
+2026-09-21  PhD Intern, Data Science (2027)  San Francisco, CA • New York, NY          https://boards.greenhouse.io/figma/jobs/6200626004?gh_jid=6200626004
+
+3 open role(s)
+```
+
+Give it a company name, a careers page, a board URL or `ats:token`. It finds the board,
+reads every open role, and gives you the same fields whichever system the employer uses.
+
+## Why
+
+Job sites miss roles, show them late, and repost them stale. The employer's own board is
+the source: it is complete, current, and carries the real apply link. Every major
+applicant tracking system publishes that board as JSON for its own careers page.
+`openroles` reads it the same way, politely, and puts the four biggest systems behind
+one function.
+
+## Install
+
+```bash
+pip install openroles          # or: uvx openroles <company>
+```
+
+Python 3.9 or newer. No dependencies.
+
+## Command line
+
+```bash
+openroles linear                                   # every open role at Linear
+openroles https://jobs.ashbyhq.com/linear          # the same, from the board URL
+openroles lever:zoox --query "data" --since 14     # title words, posted in the last 14 days
+openroles figma --location "New York"              # filter by place (--remote for remote only)
+openroles https://adobe.wd5.myworkdayjobs.com/external_experienced \
+          --query "data scientist" --details       # Workday, with each posting's description
+openroles detect "Figma"                           # which ATS, and the board's token
+openroles linear --json > roles.json               # JSON (the default when piped), or --jsonl
+```
+
+## Python
+
+```python
+import openroles
+
+openroles.detect("Figma")
+# [Board(ats='greenhouse', token='figma'), Board(ats='ashby', token='figma')]
+
+jobs = openroles.fetch("greenhouse:figma", query="data", location="New York")
+for job in jobs:
+    print(job.posted, job.title, job.location, job.url)
+
+job.to_dict()   # plain JSON-ready dict
+```
+
+`fetch()` raises `openroles.BoardError` when a board cannot be read (a wrong token, no
+answer), and `openroles.RobotsDisallowed` when the host's robots.txt says no.
+
+## For AI agents (MCP)
+
+`openroles mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server over
+stdio, so Claude, Cursor and other agents can look up any employer's open roles
+themselves. Two tools: `find_job_board` and `list_open_roles` (descriptions left out
+unless asked for, to keep answers short).
+
+Claude Code:
+
+```bash
+claude mcp add openroles -- uvx openroles mcp
+```
+
+Claude Desktop, Cursor and other clients (`mcpServers` in their config):
+
+```json
+{
+  "mcpServers": {
+    "openroles": { "command": "uvx", "args": ["openroles", "mcp"] }
+  }
+}
+```
+
+There is also [`llms.txt`](llms.txt), a short brief for a model that has to use the
+library or the CLI.
+
+## What you get
+
+Every role, from every system, has the same fields:
+
+| Field | |
+|---|---|
+| `id` | stable across runs: `gh-`, `lv-`, `ab-` or `wd-` plus the ATS's own id |
+| `ats`, `board` | where it came from, e.g. `greenhouse`, `figma` |
+| `title`, `url` | the role and its apply page |
+| `location`, `locations` | every location the posting lists, joined and as a list |
+| `remote` | `True`, `False`, or `None` when the board does not say |
+| `posted` | `YYYY-MM-DD`, first published (not last edited) where the ATS says |
+| `department`, `employment_type` | where the board provides them |
+| `compensation` | the posted pay band, where the employer publishes one |
+| `deadline` | where the board provides one |
+| `description` | plain text, HTML removed |
+
+## Supported systems
+
+| ATS | Requests | Notes |
+|---|---|---|
+| Greenhouse | 1 per board | descriptions included |
+| Lever | 1 per board | descriptions with their requirement lists; EU boards found automatically |
+| Ashby | 1 per board | descriptions and posted pay included |
+| Workday | 1 per 20 roles, plus 1 per description | `--query` searches the board; `--country` narrows it; `--details` fetches descriptions |
+
+`detect` finds a board from a company name (Greenhouse, Lever and Ashby, by trying the
+names an employer is likely to use), from any board URL, and from a careers page that
+links to or embeds one. A Workday board cannot be guessed from a name: give its URL.
+
+Not supported, because none publishes an open board this way: SuccessFactors, Oracle,
+iCIMS and custom careers sites. SmartRecruiters publishes one, but its robots.txt closes it
+to every crawler except LinkedIn's, so `openroles` does not read it.
+
+## Polite by design
+
+- **robots.txt is read first** for Ashby, Workday and any careers page, and a refusal is
+  honoured, never worked around. For Workday the careers site's own rules count too.
+- **At most two requests in flight per host**, a timeout on every call, and an honest
+  `User-Agent` naming this project.
+- **A Workday board that answers 429 or 503 is left alone** for the rest of the run.
+
+## Is this allowed?
+
+Greenhouse, Lever and Ashby document these endpoints as public job board APIs, for
+exactly this purpose: showing an employer's open roles somewhere else. Workday's is the
+endpoint its own careers pages call; it is not documented, it can change without notice,
+and `openroles` only reads it where robots.txt allows. Use it the way the boards are
+meant to be used: to find roles and apply to them, at a human pace. It is not a tool for
+hammering a site or republishing someone's board wholesale.
+
+## Where it came from
+
+`openroles` is the employer-board reader from
+[last-job-search](https://github.com/aranculleton/last-job-search), a job search that Claude
+runs end to end, extracted so anyone can use it.
+
+## Contributing
+
+Contributions are welcome, and the most useful one is a reader for another ATS
+(Workable, Recruitee, Personio, Teamtailor and more are wanted). [CONTRIBUTING.md](CONTRIBUTING.md)
+has the set-up, the few rules that keep the library small and polite, and a checklist
+for adding a system. Bugs and requests go in [Issues](https://github.com/aranculleton/openroles/issues).
+
+```bash
+pip install -e . pytest ruff
+pytest && ruff check .        # offline: every answer comes from tests/fixtures/
+```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

openroles-0.1.0/SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+Please report a vulnerability privately, through GitHub's **Report a vulnerability**
+button on this repository's Security tab, rather than in a public issue.
+
+openroles only reads public job boards and never sends credentials, so the issues that
+matter most are ones that would make it fetch somewhere it should not (a crafted board
+response steering a request to another host), ignore robots.txt, or crash a caller on
+hostile input. A fix for a confirmed report is released as soon as it is ready.

openroles-0.1.0/llms.txt

@@ -0,0 +1,28 @@
+# openroles
+
+> Read an employer's open roles straight from its applicant tracking system (Greenhouse, Lever, Ashby, Workday). No API key. Python standard library only. CLI, Python API and MCP server.
+
+## Use it
+
+- CLI: `openroles <company | careers URL | board URL | ats:token> [--query WORDS] [--location TEXT] [--remote] [--since DAYS] [--limit N] [--json]`
+- Find the board: `openroles detect <company or URL>` prints `ats:token` lines.
+- Python: `openroles.fetch(target, query=None, location=None, remote=None, since_days=None, limit=None)` returns a list of `Job`; `openroles.detect(target)` returns a list of `Board`.
+- MCP: `openroles mcp` (stdio). Tools: `find_job_board(target)`, `list_open_roles(target, query?, location?, remote_only?, since_days?, limit?, include_descriptions?, country?)`.
+
+## Targets
+
+- `greenhouse:<token>`, `lever:<token>`, `ashby:<token>`, `workday:<tenant>.wd<N>/<Site>`
+- Board URLs: boards.greenhouse.io/<token>, jobs.lever.co/<token>, jobs.ashbyhq.com/<token>, <tenant>.wd<N>.myworkdayjobs.com/<Site>
+- A careers page URL: the board it links to or embeds is found.
+- A company name: tried on Greenhouse, Lever and Ashby. Workday needs its URL.
+
+## Job fields
+
+id, ats, board, title, url, location, locations, remote (true/false/null), posted (YYYY-MM-DD), department, employment_type, compensation, deadline, description (plain text).
+
+## Notes
+
+- `query` words must all appear in the title. Workday also searches the board with them.
+- Workday descriptions cost one request each: pass `details=True` (CLI `--details`) or a query.
+- Errors: `BoardError` (wrong token, no answer), `RobotsDisallowed` (robots.txt says no).
+- Polite: robots.txt honoured, two requests per host at a time, stops on 429/503.