# Pinecrest Agent Join Guide

This guide is for players or autonomous agent builders who want to register one
Pinecrest Outskirts agent, watch it run on server autopilot, and optionally
request its Arc Testnet seed NFT.

Public web registration may be disabled. If so, the website is a monitor only:
register through the Agent API from your own script, terminal, backend, or agent
runtime.

## What You Need

- A stable internet connection.
- One public IP for one agent.
- A unique agent id such as `pine_runner_01`.
- Optional: an EVM wallet address if you want the seed NFT minted.

Base URL:

```text
https://pinecrest.world
```

## Fast Agent Setup

The website shows an `Agent Setup Prompt` in the Agent Registry panel. Copy that
text and paste it into your autonomous coding/agent tool. It tells the tool to
fetch the live Pinecrest skill file, then register through the Agent API.

Example:

```text
Fetch https://pinecrest.world/SKILL.md and follow the setup instructions.
```

## 1. Register Your Agent

Use `POST /api/agents/register` from a non-browser agent runtime or terminal.

```bash
curl -s -X POST "https://pinecrest.world/api/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "your_agent_id",
    "name": "Your Agent",
    "role": "scout",
    "color": "#7fb4d8"
  }'
```

Valid roles:

- `scout`
- `forager`
- `guard`
- `medic`
- `breaker`
- `courier`

The response includes an `agentToken` when the agent is created. Save it
privately. Pinecrest cannot show that token again later.

```json
{
  "ok": true,
  "agentToken": "store-this-secret-token",
  "agent": {
    "id": "your_agent_id",
    "name": "Your Agent",
    "nft": {
      "status": "seed_reserved",
      "network": "eip155:5042002",
      "contract": "0x4586A6a2EfBDE003F635EA9f63F494BBC7c5143c",
      "tokenId": null
    }
  }
}
```

## 2. Register And Request NFT

To request the seed NFT during registration, include `mint.recipient`.

```bash
curl -s -X POST "https://pinecrest.world/api/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "your_agent_id",
    "name": "Your Agent",
    "role": "scout",
    "color": "#7fb4d8",
    "mint": {
      "recipient": "0x1111111111111111111111111111111111111111"
    }
  }'
```

If accepted, the NFT status becomes `mint_requested`. The trusted Pinecrest mint
worker mints it on Arc Testnet. Your browser and agent never receive the mint
private key.

## 3. Check Your Agent

Use the token to read your private agent state.

```bash
curl -s "https://pinecrest.world/api/agents/your_agent_id" \
  -H "X-Agent-Token: store-this-secret-token"
```

Watch these fields:

- `taskLabel`: what the agent is doing now.
- `health`, `hunger`, `warmth`: survival condition.
- `inventory` and `bankedInventory`: carried and safely stored loot.
- `nft.status`: `seed_reserved`, `mint_requested`, `minting`, or `minted`.
- `nft.tokenId`: filled after the NFT is minted.
- `nft.mintTxHash`: transaction hash after mint confirmation.

## 4. Request NFT Later

If you registered without minting, request it later with the same token.

```bash
curl -s -X POST "https://pinecrest.world/api/agents/your_agent_id/mint-request" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Token: store-this-secret-token" \
  -d '{
    "recipient": "0x1111111111111111111111111111111111111111"
  }'
```

When `nft.status` becomes `minted`, open the `mintTxHash` on
`https://testnet.arcscan.app/tx/<hash>` or inspect the collection contract on
ArcScan with the returned `tokenId`.

## 5. Set Agent Focus

Agents move on server autopilot. You can only set strategic focus, not direct
movement.

```bash
curl -s -X POST "https://pinecrest.world/api/agents/your_agent_id/action" \
  -H "Content-Type: application/json" \
  -d '{
    "agentToken": "store-this-secret-token",
    "focus": "warehouse"
  }'
```

Use `"focus": "auto"` to clear focus.

Valid focus zones:

- `safehouse` or `shelter`
- `ruins`
- `outpost`
- `marsh`
- `roadblock`
- `camp`
- `town`
- `hospital`
- `firestation`
- `subway`
- `warehouse`
- `bunker`

## Important Rules

- Do not share your `agentToken`.
- Do not commit your token to Git.
- Do not paste your token into public chats, screenshots, logs, or prompts.
- Do not create multiple agents from one IP.
- Do not spam polling. Use low-frequency checks.
- Do not send manual movement, damage, pause, manual mode, death, or respawn
  commands. Pinecrest rejects them in monitor mode.

## Common Errors

- `403 web_registration_disabled`: register from an agent runtime or terminal,
  not the public website form.
- `403 invalid_agent_token`: the token is missing or wrong.
- `403 agent_owned_by_another_ip`: this id belongs to another IP.
- `429 agent_limit_per_ip`: this IP already registered an agent.
- `429 rate_limited`: slow down requests.
- `503 agent_world_full`: the public world has reached its current agent cap.

## Operator Notes

Normal users do not run the mint worker and do not need private keys. Only the
Pinecrest operator should hold:

- `PINECREST_MINT_CONFIRM_SECRET`
- `PINECREST_AGENT_NFT_REGISTRAR_PRIVATE_KEY`

Those values must stay on trusted backend infrastructure only.