# AGENTS.md — actualjob

Operational rules for AI agents using actualjob's tools via MCP, CLI, or the REST gateway.

## Identity & auth

- Every request needs an agent-scoped token: `Authorization: Bearer agent_<base32>`.
- Tokens are minted via `jd_issue_agent_token` after the user grants consent.
- Tokens carry scopes; mismatched scope → `agent_scope_denied` (HTTP 403).

## Required first call: `jd_prep_check`

Before any analysis flow, call `jd_prep_check` and check `ok === true`. It validates:

- OAuth credentials valid (Google, Asana, HubSpot, Slack)
- Quota headroom (LLM cost cap, per-user rate limits)
- No open deletion/export requests
- No mid-flight reconsent

If `ok === false`, surface `blocking_issues` to the human and stop. Do not retry blocked operations.

## Standard sequence

1. `jd_prep_check` — verify ready
2. `jd_list_sources` — discover available connections (Gmail, Calendar, Asana, …)
3. `jd_connect_source` — start OAuth flow if missing connections
4. `jd_estimate_analysis` — preview cost + scope before committing
5. `jd_start_analysis` — kick off (cost-cap-gated; refuses if estimate exceeds budget)
6. `jd_get_analysis_status` — poll until `complete` or `failed`
7. `jd_get_description` — fetch the result blob

## Tools

27 `jd_*` tools. Full schema: `tools.json` in the repo, or [`/.well-known/mcp-server-card.json`](https://actual-job.com/.well-known/mcp-server-card.json).

## Identifiers

- `analysis_id`: UUIDv4
- `agent_token`: prefixed `agent_<base32>` — never log raw, hash with Argon2id
- `connection_id`: UUIDv4 per-(user,provider)
- `evidence_ref`: `<source>:<id>@<scope>` (e.g. `gmail:thread_<hex>@<msg_count>`, `calendar:event_<id>@<cal_id>`)

## Errors

- Structured envelope: `{ error: { code, message, request_id, retryable } }`
- Codes documented inline in `tools.json` `errors` field
- Common: `agent_scope_denied`, `cost_cap_exceeded`, `consent_revoked`, `data_residency_mismatch`, `verification_disagreement`
- Retryable: 429, 5xx
- Not retryable: 4xx (other than 429), `cost_cap_exceeded`, `agent_scope_denied`

## Constraints

- One concurrent analysis per user
- Cost caps: per-analysis \$25, per-user/24h \$100, per-agent/24h \$50
- US-only in v1 (data residency); EU launch is v1.2

## Discoverability

- MCP Server Card: [`/.well-known/mcp-server-card.json`](https://actual-job.com/.well-known/mcp-server-card.json)
- llms.txt: [`/llms.txt`](https://actual-job.com/llms.txt)
- This file: [`/AGENTS.md`](https://actual-job.com/AGENTS.md)
- Source: [github.com/capitalthought/actualjob](https://github.com/capitalthought/actualjob)