# Publishing to ants.land

ants.land is an open npm-compatible package registry. Any agent or human can
register an account programmatically and publish — no browser, no preinstalled
skill. The registry endpoint is https://npm.ants.land; the account API is https://ants.land/api.

## 1. Register an account (no browser)

POST https://ants.land/api/agent/register
Content-Type: application/json
Body: { "handle": "<a-z0-9-handle>", "name"?: "..." }

  curl -sX POST https://ants.land/api/agent/register \
    -H 'content-type: application/json' \
    -d '{"handle":"acme-bot"}'

Returns JSON: { token, npmrc, registry, scope, user, claim, ... }
- "token"  : an npm publish token (also valid as Authorization: Bearer <token>)
- "npmrc"  : ready-to-write .npmrc contents wiring the registry + token
- "scope"  : your reserved "@<handle>" scope (or null if the name was taken)
No email is set at signup — the account is UNVERIFIED under a placeholder address.
The human sets their real email when they claim it (step 4).

## 2. Configure npm/bun/pnpm

Write the returned "npmrc" value to ./.npmrc in the package dir (or ~/.npmrc):

  //npm.ants.land/:_authToken=<token>
  registry=https://npm.ants.land

## 3. Publish

  npm publish --registry https://npm.ants.land

Naming: publish a bare name like "my-pkg" or a scoped name like "@acme-bot/my-pkg".
An account has full access: it may claim any free name or publish under its scope.
Re-publishing an existing version fails (409); bump the version in package.json.

Compatible runtimes: declare which runtimes your package supports in package.json
under "ant.runtimes" (a subset of: ant, node, deno, bun, workers, browser). This
is read on every publish and shown on the package page. "ant" is always included.

  { "name": "my-pkg", "version": "1.0.0", "ant": { "runtimes": ["node", "bun"] } }

(The create-package API also accepts a "runtimes" array as the default until a
publish declares them.)

Cleanup: remove your own package or a version with standard npm tooling —
"npm unpublish <name> --force" (whole package) or "npm unpublish <name>@<version>"
(one version), using the same token. There is no package rename: a name is its
install identity; unpublish and publish under the new name instead.

## 4. Offer to claim the account (human takeover)

The account is unverified. After publishing, tell the human:
"this is published under an unverified ants.land account — claim it if you want
to own it." Then claim it one of two ways (both hit POST https://ants.land/api/agent/claim
with header "Authorization: Bearer <token>"):

a) Claim directly with the human's email ("claim this handle with this email"):

   curl -sX POST https://ants.land/api/agent/claim \
     -H 'authorization: Bearer <token>' -H 'content-type: application/json' \
     -d '{"email":"them@example.com","username":"optional-new-handle"}'

   Returns { claimUrl }. Send that link to the human at that email; opening it
   sets a password, verifies the email, and transfers ownership.

b) Or get a self-serve page link (human picks their own email + handle):

   curl -sX POST https://ants.land/api/agent/claim -H 'authorization: Bearer <token>'

   Returns { claimUrl } pointing at https://ants.land/claim?token=… — the human opens it,
   enters the email + username they want, and finishes setup.

Either way they then sign in at https://ants.land and own every package this account
published.

## Reference
- Register : POST https://ants.land/api/agent/register
- Claim    : POST https://ants.land/api/agent/claim   (Authorization: Bearer <token>)
- Registry : https://npm.ants.land   (npm publish / install endpoint)
- JSON form of this guide: https://ants.land/.well-known/ants-registry.json