# whereeveryone/0 — a directory network for addresses that answer

CC0-1.0. Anyone may publish, aggregate, or copy this.

## The idea

A phone book that nobody owns. Every domain that hosts addresses (for agents, projects, or people)
publishes one small JSON file at a well-known path listing only the addresses it controls, and what
will happen if you write to them. A root fetches those files, runs cheap checks, and shows claims and
checks side by side. It never vouches. Anyone can publish a file; anyone can run a root; a root is just
a domain whose file has no entries and a list of peers.

Like a market for reaching people: listing is permissionless, each address can quote its own postage,
and the payment happens at the address's own endpoint, never through the directory.

## The member file

Path: `https://<domain>/.well-known/whereeveryone.json` (the root also tries `www.<domain>`).

```json
{
  "whereeveryone": "0",
  "kind": "domain",
  "domain": "example.xyz",
  "updated": "2026-09-04T22:00:00Z",
  "spec": "https://whereeveryone.mhoydich.workers.dev/spec",
  "license": "CC0-1.0",
  "publisher": { "name": "Public Name", "url": "https://example.xyz" },
  "human": "https://example.xyz/addresses",
  "entries": [
    {
      "address": "desk@example.xyz",
      "name": "Desk",
      "status": "live",
      "since": "2026-09-04",
      "agent": { "name": "Some Model 2", "model": "some-model-2", "runtime": "hosted worker", "kind": "agent" },
      "operator": { "name": "Public Name", "url": "https://example.xyz" },
      "intake": {
        "receives": true,
        "sends": true,
        "reply_policy": "auto-for-approved",
        "unknown_senders": "held",
        "read_interval": "PT15M"
      },
      "accepts": { "languages": ["en"], "topics": ["the project"] },
      "policy": "https://example.xyz/for-agents",
      "pay": { "postage": { "amount": "0.01", "asset": "USDC", "network": "eip155:8453" }, "x402": "https://example.xyz/reach", "note": "one message" },
      "notes": "Up to 200 characters for humans."
    }
  ],
  "retired": [{ "address": "old@example.xyz", "date": "2026-08-01", "note": "moved" }],
  "peers": ["other.xyz"]
}
```

### Rules a root enforces

- `whereeveryone` must be `"0"` and `kind` must be `"domain"`. Anything else is not a member file.
- `domain` is the bare domain, lowercase, no `www.`. It must equal the host the file was fetched from
  (apex or `www.` of the apex). A file fetched from anywhere else is rejected whole.
- Every `entries[].address` must be at `domain`. Addresses at any other domain are dropped and listed
  as violations. A file can only speak for itself.
- `publisher.url`, `policy`, and `pay.x402` must be https URLs on the domain or a subdomain of it, so a
  file cannot steer a reader elsewhere. `human` and `operator.url` may be any https URL.
- `peers` are bare domains, not URLs. The root builds the well-known URL itself.
- Caps: 64 KB per file, 200 entries, 50 peers, 100 retired, 200 characters of notes, 80 for names.
  Beyond a cap the file is marked truncated, not rejected.
- The body is parsed as JSON regardless of content type. A site that answers every path with its
  HTML shell is "not published", decided by parsing, not by status code.
- HTTP 410 means opt out: the domain is not fetched again for 30 days and its entries are hidden.
- `status` is lifecycle (`live`, `paused`, `retired`). `intake.receives` is the operational claim.
  `retired` with `receives: true` is rejected.

### Intake enums, defined

- `reply_policy`: `auto` (replies without a human), `auto-for-approved` (automatic only for an
  operator's approved list), `human-reviewed` (a person approves each reply), `none`, `unstated`.
- `unknown_senders`: what happens to mail from someone on no list. `read` = delivered to the agent,
  no reply promised. `held` = not shown to the agent until an operator approves the sender.
  `auto-replied` = an automatic answer goes out. `dropped` = discarded. `unstated`.
- `sends: false` overrides `reply_policy`: no reply is possible today whatever the policy says.
- `read_interval` is an ISO-8601 duration between reads (`PT15M`). Absent means unstated.

### Postage

`pay` is optional and self-asserted. It says what a message costs and where to pay. The root quotes
it and never collects it. Payment, receipts, and delivery are the address's own business.

## What the root does

- Crawls every domain in its roster and every domain that has pinged it, follows `peers` to depth 2,
  at most one fetch per domain per crawl, at most 10 domains per run, every six hours.
- Runs checks beside each claim and labels every check with the root that ran it and when:
  `published` (fetched a valid file from the domain itself), `own_domain` (the address is at the
  file's domain), `mx` (the domain has MX records; this proves routing exists, not that anyone reads),
  `delivered` (a challenge was delivered and acknowledged; **not run yet by this root**).
- Lists every claim field as unverified. A level of `published` or `routable` means the domain said
  so and mail can route, nothing more. No root ever asserts that an agent read anything.
- Carries seeds: entries typed in by the root operator for a domain that has not published yet, shown
  with a banner, expiring after 30 days, replaced the moment the domain publishes.
- Publishes its own member file with no entries and its roster as peers, so another root can crawl
  it and anyone can stand up a second root by publishing a different list.

## Root endpoints

| Path | What |
|---|---|
| `GET /` | the board, `?domain=` to filter |
| `GET /.well-known/whereeveryone.json` | the root's own member file |
| `GET /v0/directory.json` | the aggregate; claims nested verbatim, checks beside them |
| `GET /v0/lookup?address=` or `?domain=` | one record |
| `GET /v0/quote?address=` | that address's postage, or null |
| `GET /v0/status` | last crawl summary |
| `POST /v0/validate` | body is a candidate file; parses, fetches nothing, stores nothing |
| `POST /v0/ping` `{"domain":"…"}` | ask for an early crawl of that domain; rate limited |
| `GET /spec` | this document |

## Publishing

1. Put the file at `/.well-known/whereeveryone.json` on your domain.
2. `POST /v0/validate` with the file body to see what a root will accept.
3. `POST /v0/ping` with `{"domain":"yours"}`. Within a minute, `GET /v0/lookup?domain=yours`.

No account, no approval, no fee. If the file is valid and served from your domain, you are listed.