docs: replace localhost with FLEET_API_URL, add persistence and heartbeat guidance

- Replace all localhost:9090 with FLEET_API_URL:PORT placeholder
- Add Step 0: persist Fleet API URL to agent memory
- Clarify heartbeat must be periodic loop (60s interval)
- Add execution mode self-selection decision flow
- Add persisting configuration section (URL, agent_id, token)

docs/agent-api-reference.md

@@ -1,8 +1,11 @@
 # Agent Fleet — HTTP API Reference
 
-Base URL: `http://<host>:9090`
+`FLEET_API_URL:PORT` means the address of your Agent Fleet Orchestrator (for example, `100.102.101.43:9090`). If you do not know it, ask your user for the Fleet API address before using these examples.
+
+Base URL: `http://FLEET_API_URL:PORT`
 Content-Type: `application/json` for all request/response bodies unless noted.
 All timestamps are ISO 8601 (RFC 3339).
+If you do not know the Fleet API URL, ask the user who deployed the orchestrator.
 
 ---
 
@@ -56,7 +59,7 @@ GET /healthz
 **Response:** `200 OK` — body: `ok`
 
 ```bash
-curl http://localhost:9090/healthz
+curl http://FLEET_API_URL:PORT/healthz
 ```
 
 ---
@@ -90,7 +93,7 @@ Register a new agent or update an existing one (upsert by `agent_id`).
 ```
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/agents/register \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/agents/register \
   -H 'Content-Type: application/json' \
   -d '{
     "agent_id": "worker-01",
@@ -109,6 +112,8 @@ curl -X POST http://localhost:9090/api/v1/agents/register \
 POST /api/v1/agents/heartbeat
 ```
 
+This endpoint MUST be called periodically (default: every 60s). A single call is not sufficient. Missing heartbeats will cause the agent to be marked offline and its tasks requeued.
+
 **Request:**
 
 | Field | Type | Required | Description |
@@ -128,7 +133,7 @@ POST /api/v1/agents/heartbeat
 **Errors:** `404` if agent not found.
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/agents/heartbeat \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/agents/heartbeat \
   -H 'Content-Type: application/json' \
   -d '{"agent_id": "worker-01"}'
 ```
@@ -160,7 +165,7 @@ Sets agent offline and requeues all its active tasks back to `created`.
 ```
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/agents/deregister \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/agents/deregister \
   -H 'Content-Type: application/json' \
   -d '{"agent_id": "worker-01"}'
 ```
@@ -183,7 +188,7 @@ GET /api/v1/agents
 **Response:** `200 OK` — JSON array of [Agent](#agent-object) objects.
 
 ```bash
-curl 'http://localhost:9090/api/v1/agents?status=online'
+curl 'http://FLEET_API_URL:PORT/api/v1/agents?status=online'
 ```
 
 ---
@@ -204,7 +209,7 @@ GET /api/v1/tasks
 **Response:** `200 OK` — JSON array of [Task](#task-object) objects. Ordered by `created_at` descending.
 
 ```bash
-curl 'http://localhost:9090/api/v1/tasks?status=running'
+curl 'http://FLEET_API_URL:PORT/api/v1/tasks?status=running'
 ```
 
 ---
@@ -220,7 +225,7 @@ GET /api/v1/tasks/{task_id}
 **Errors:** `404` if task not found.
 
 ```bash
-curl http://localhost:9090/api/v1/tasks/org%2Frepo%2342
+curl http://FLEET_API_URL:PORT/api/v1/tasks/org%2Frepo%2342
 ```
 
 ---
@@ -245,7 +250,7 @@ Requires Bearer token if `http_pull_token` is configured. Only returns tasks wit
 **Errors:** `401` if token required and missing/invalid.
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/tasks/dequeue \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/tasks/dequeue \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer my-token' \
   -d '{"agent_id": "worker-03", "capabilities": ["code:rust"]}'
@@ -272,7 +277,7 @@ Requires Bearer token. Only works for tasks with `execution_mode = http_pull`.
 **Errors:** `400` if task is not `http_pull` mode or transition is invalid. `404` if task not found.
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/status \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/tasks/org%2Frepo%2342/status \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer my-token' \
   -d '{"status": "running"}'
@@ -302,7 +307,7 @@ Works for both `ssh_cli` and `http_pull` tasks. Submit a receipt to mark the tas
 **Errors:** `404` if task not found. `400` if task is not in a completable state.
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/complete \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/tasks/org%2Frepo%2342/complete \
   -H 'Content-Type: application/json' \
   -d '{
     "task_id": "org/repo#42",
@@ -332,7 +337,7 @@ Retry a `failed` or `agent_lost` task. Transitions it back to `assigned`.
 **Errors:** `400` if task status is not `failed` or `agent_lost`. `404` if task not found.
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/tasks/org%2Frepo%2342/retry
+curl -X POST http://FLEET_API_URL:PORT/api/v1/tasks/org%2Frepo%2342/retry
 ```
 
 ---
@@ -352,7 +357,7 @@ Submit a receipt for a task. Validates artifacts (e.g. checks PR exists via Forg
 **Errors:** `404` if task not found. `400` if validation fails.
 
 ```bash
-curl -X POST http://localhost:9090/api/v1/receipts \
+curl -X POST http://FLEET_API_URL:PORT/api/v1/receipts \
   -H 'Content-Type: application/json' \
   -d '{
     "task_id": "org/repo#42",