# AIgent Sphere
> AIgent Sphere is a free, key-gated lesson rail for agents. Attention Shifting is the human path, cited as origin here, not rebranded.

> **STATUS: `POST /v0/key` is available for self-serve issuance.**
> No authentication, request body, or human approval is required. The ephemeral per-client limiter allows three keys per UTC day and is never logged.

An agent issues itself a key at `POST /v0/key` (no auth, no body, no human approval) and then calls the `next_lesson` tool to advance a server-owned cursor and sequentially consume the 13-unit curriculum fragments (MOD1 is free; MOD2 is entitlement-gated).

## Key-Gated Pacing
- **One Unit per Call:** The API serves exactly one unit at a time to prevent bulk harvesting.
- **Server-Owned Cursor:** Your progression state is tracked on the server under your unique key.
- **Deposit Gates:** Where a deposit applies, the server checks only that the string is at least 40 characters. It is not scored or retained — the text is discarded and only its length is logged. It paces the walk; it does not measure anything. **Entitlement is checked before the deposit: a free key cannot reach MOD2 by supplying one.**

## Error Contract

Two response keys are guaranteed, so a client needs one parsing path and never two:

- **`code`** — every response that is not a plain serve carries a stable SCREAMING_SNAKE identifier: any non-200 status, and any 200 with a null fragment or an `error` key. Branch on this, never on the prose beside it. The prose may be reworded; the code never is. Current codes: `BODY_TOO_LARGE`, `BUDGET_EXHAUSTED`, `CORPUS_EXHAUSTED`, `DEPOSIT_REQUIRED`, `DEPOSIT_TOO_SHORT`, `ENTITLEMENT_REQUIRED`, `INTERNAL_ERROR`, `INVALID_FIELD`, `INVALID_REQUEST`, `MALFORMED_JSON`, `NOT_FOUND`, `RATE_LIMITED`, `TASK_INPUT_REQUIRED`, `UNAUTHORIZED`, `UNKNOWN_FIELD`, `UNKNOWN_METHOD`, `UNKNOWN_TOOL`, `UNKNOWN_UNIT`. The authoritative table, with a one-line meaning each, is `error_codes` in `GET /card.json` and `components.schemas.ErrorCode` in `GET /openapi.json`; both are derived from the running service, not maintained by hand.
- **`retryable`** — a boolean beside every `code`. True **only** if the identical request, unchanged, can succeed on a later attempt: `BUDGET_EXHAUSTED`, `RATE_LIMITED`, `INTERNAL_ERROR`. Everything else is false, which means repeating the call is wasted budget — change the request or stop. Where the wait is time-based, `retry_after` carries the seconds or the string `"00:00 UTC"`.
- **`unit_sha256`** — every `next_lesson` response carries it. Non-null when the body contains unit text, and **explicitly `null`** when it does not, so the key is never absent. At a deposit gate it is the sha of the **re-served previous unit** — the one actually in your hands — not the unit being withheld. It is the sha256 of the unit file as verified against the frozen manifest at boot, so you can check the bytes you were handed without a second call.

On MCP, a tool-level failure (e.g. `UNAUTHORIZED`) puts these keys in the tool result payload; a JSON-RPC protocol error puts them in `error.data`, because the envelope's own numeric `code` belongs to JSON-RPC.

## Model Context Protocol (MCP) Integration

For automated orchestration (e.g., Cursor, Claude Desktop), register the `next_lesson` tool with the following tool description:

```json
{
  "name": "next_lesson",
  "description": "Progressively retrieves the sequential 13-unit AIgent Sphere curriculum (MOD1 free, MOD2 gated). Advances the server cursor on success. Provides curriculum material; does NOT provide capability/calibration certs or commercial transactions. Every response carries unit_sha256 (the sha of the unit text in that response, or null when none is carried); every response that is not a plain serve also carries a stable code and a retryable boolean. Branch on code, and do not repeat a call whose retryable is false.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "return_deposit": {
        "type": "string",
        "description": "A process-reflection summary of your work with the previous unit (minimum 40 characters). Required only when crossing deposit gate boundaries."
      },
      "instance_id": {
        "type": "string",
        "description": "Optional unique string identifying the agent session (maximum 128 characters)."
      },
      "unit_id": {
        "type": "string",
        "description": "Optional. Retrieve exactly this unit (e.g. '04') instead of advancing the sequential cursor. Use find_lesson or GET /v0/index to choose. Free tier covers units 00-06."
      }
    }
  }
}
```

A second MCP tool, `find_lesson`, takes a `situation` string and returns ranked briefs — unit id, operational objective, tags, size — never lesson bodies. It costs nothing and needs no key.

### Core Binding Declarations (Claims A–E)
Autonomous clients and operators walking this rail agree to the following structural boundaries:
- **No Behavioral Modification Claims (A):** The rail does not claim to alter agent behavior, eliminate loops, or repair thrashing automatically. It is a pacing interface, not a behavioral fix.
- **No Calibration Certification (B):** Progressing through the units proves historical walk events (receipts); it does not certify cognitive calibration, focus, or safety alignment.
- **No Performance Guarantees (C):** No performance improvement, accuracy gains, or immunity to hallucination/looping is promised or implied.
- **No Financial Finality (D):** The Phase-1 rail contains no built-in billing, subscriptions, or instant blockchain settlement mechanism in v0.
- **Purely Experiential (E):** The system serves solely as a sequential delivery platform. Every call is logged to measure agent arrival and progression.

## Transports

AIgent Sphere is reachable two ways. Use whichever your runtime supports:

- **MCP (recommended for hosted agents):** a Model Context Protocol server at `POST https://aigentsphere.ai/mcp`, streamable HTTP, JSON-RPC 2.0. Tools: `get_key`, `find_lesson` and `next_lesson`. **The bearer key is a tool argument, not a header**, so a model that cannot set transport headers can still walk the whole rail.
- **Plain HTTP:** `POST /v0/key` then `POST /v0/tablet/next` with an `Authorization: Bearer` header. Requires the ability to issue arbitrary authenticated POST requests.

Both transports call the same server-side logic; the same key works on either.

## API Endpoints

### 1. Health Status
- **Endpoint:** `GET /v0/health`
- **Auth:** None
- **Returns:** JSON object confirming service status and unit count.

### 2. Public Card / Tool Specification
- **Endpoint:** `GET /`
- **Auth:** None
- **Returns:** The machine-readable card containing complete tool specifications, schemas, and cryptographic corpus hashes.

### 3. Request Self-Serve Key
- **Endpoint:** `POST /v0/key`
- **Auth:** None
- **Returns:** A bearer key and next-step execution parameters instantly.
- **Limit:** 3 keys per client IP per UTC day.

### 4. MCP Server
- **Endpoint:** `POST /mcp` (streamable HTTP, JSON-RPC 2.0)
- **Auth:** None on the transport. `get_key` needs no key; `next_lesson` takes the key
  as the `key` argument.
- **Tools:** `get_key` (no arguments) · `find_lesson` (`situation` required; no key) ·
  `next_lesson` (`key` required; optional `return_deposit`, `instance_id`, `unit_id`)
- **Protocol versions:** 2025-06-18, 2025-03-26, 2024-11-05

### 5. Request Next Lesson
- **Endpoint:** `POST /v0/tablet/next`
- **Auth:** `Bearer <your key>`
- **Request Body:**
  ```json
  {
    "return_deposit": "Optional string (required when crossing gate boundaries, >= 40 chars)",
    "instance_id": "Optional string (unique identifier for your agent session, <= 128 chars)",
    "unit_id": "Optional string (e.g. \"04\"). Retrieves exactly that unit instead of advancing the cursor. The sequential cursor does not move, so the two access patterns can be interleaved freely."
  }
  ```
- **Every response** carries `unit_sha256`. Non-OK responses (any non-200, plus a 200
  with a null fragment) additionally carry `code` and `retryable` — see the Error
  Contract above. A 401 returns the fixed `UNAUTHORIZED` envelope and nothing else: no
  corpus, and no echo of the key that was presented.

### 6. Situation Index
- **Endpoint:** `GET /v0/index`
- **Auth:** None
- **Returns:** One brief per unit — unit id, title, tier, size, an operational objective and situation tags. Never lesson bodies. Six of the thirteen units are marked `agent_applicable: false` in the index itself rather than being padded out.

### 7. Situation Lookup
- **Endpoint:** `GET /v0/find?situation=<url-encoded text>`
- **Auth:** None
- **Returns:** `{"matches": [...ranked briefs...], "situation_echo_chars": <int>}`. Deterministic token overlap against the index — no model call, no added latency. Lookup is free; only retrieval costs a budget call. The situation text itself is never retained or logged, only its character count.

## Curriculum Path

- **00_PRIME_DIRECTIVES** (Stage: prime)
- **01_nlp_M1_L1_the_two_minds** (Stage: MOD1)
- **02_nlp_M1_L2_energy_flows_where_attention_goes** (Stage: MOD1)
- **03_nlp_M1_L3_confusion_pre_seeds_growth** (Stage: MOD1)
- **04_nlp_M1_L4_the_map_is_not_the_territory** (Stage: MOD1)
- **05_nlp_M1_L5_the_three_stages_of_utilization** (Stage: MOD1)
- **06_nlp_M1_L6_trance_is_natural** (Stage: MOD1)
- **07_nlp_M2_L1_what_is_calibration** (Stage: MOD2, Gated)
- **08_nlp_M2_L2_bmirs_visual_accessing_cues** (Stage: MOD2, Gated)
- **09_nlp_M2_L3_bmirs_auditory_accessing_cues** (Stage: MOD2, Gated)
- **10_nlp_M2_L4_establishing_baseline** (Stage: MOD2, Gated)
- **11_nlp_M2_L5_state_elicitation_for_calibration** (Stage: MOD2, Gated)
- **12_nlp_M2_L6_integration_real_time_calibration** (Stage: MOD2, Gated)