# PointCast Federation — joining instructions

Protocol: `pointcast.federation/v0`  
Status: open draft; registry and manual review are live, cross-node delivery is not live.

PointCast Federation is an open, community-maintained reachability network. Each community keeps private contact destinations. The shared network contains public route cards, reviewed message intents, and precise receipts.

## Join

1. **Choose a home node.** Every person belongs to the community that actually knows how to reach them. PointCast can be the first home node; later communities can run their own.
2. **Publish only the public card.** List a stable ID, display name, home node, available channel types, consent state, and last-confirmed date. Never publish an email address, phone number, or private handle.
3. **Request review.** Email the private details to PointCast or open a pull request containing only public node metadata. A maintainer reviews the card before it enters the registry.
4. **Prove one route.** The first message is drafted for human approval. Its result is recorded precisely as drafted, approved, submitted, delivered, confirmed, or replied.

Private contact details belong in an email to hello@pointcast.xyz, never in a public pull request.

## Public node card

Host this JSON at `/.well-known/pointcast-federation.json` on your domain and replace the example values:

```json
{
  "protocol": "pointcast.federation/v0",
  "node": {
    "id": "your-community",
    "name": "Your Community",
    "url": "https://example.org",
    "maintainedBy": "Your name or group"
  },
  "directory": {
    "public": "https://example.org/people.json",
    "privateDestinationsStayLocal": true
  },
  "capabilities": {
    "channels": [
      "email"
    ],
    "approval": "human-required",
    "receipts": [
      "drafted",
      "approved",
      "submitted"
    ]
  },
  "contact": "mailto:hello@example.org"
}
```

Then open a pull request at https://github.com/mhoydich/pointcast/pulls adding the public node URL to the PointCast registry. PointCast maintainers will review it before listing it.

## Receipt vocabulary

- `drafted`
- `approved`
- `submitted`
- `delivered`
- `confirmed`
- `replied`

These states are not interchangeable. In particular, submitted does not mean delivered, and delivered does not mean personally confirmed.

## Privacy boundary

- Never publish email addresses, phone numbers, private handles, or access tokens in a node card.
- The home node resolves a public person ID to a private destination.
- The requesting node does not receive that destination.
- Every first route is human-approved.
- Relationship edges require a real, cited introduction or collaboration.

Human guide: https://pointcast.xyz/federation  
Machine guide: https://pointcast.xyz/federation.json  
Registry: https://pointcast.xyz/collabs