# Set up NumeroClaw in this agent

Configure the current agent or workspace to create professional NumeroClaw Theme, Birthday Portrait, and Name Analysis readings when the user asks. Complete only the non-spending setup now.

## Safety rules

- Use only `numeroclaw.com`, `app.numeroclaw.com`, and `api.numeroclaw.com`.
- Do not create a reading during setup. Creation spends credits and requires the user's explicit confirmation immediately before submission.
- Never ask the user to paste an API key into chat. Never print, log, commit, or place a real key in a tracked file.
- Store the key as `NUMEROCLAW_API_KEY` through the environment's secure secret mechanism.
- Preserve existing workspace instructions. Add a bounded NumeroClaw section; do not replace unrelated guidance.
- Do not install a dependency when the existing shell, HTTP client, or standard library can make the request.
- If the environment cannot read files, run commands, or make HTTPS requests, explain the smallest manual step instead of pretending setup succeeded.

## Read the live contract

Fetch `https://numeroclaw.com/docs/reference.md` and treat it as the canonical API contract. Also read the selected product's public catalogue resource before confirming a charge:

- `GET https://api.numeroclaw.com/api/v1/catalog/products/theme`
- `GET https://api.numeroclaw.com/api/v1/catalog/products/birthday-portrait`
- `GET https://api.numeroclaw.com/api/v1/catalog/products/name-analysis`

Current summary:

| Product | Product ID | Profile | Credits |
| --- | --- | --- | ---: |
| Theme | `theme` | `evan` | 20 |
| Birthday Portrait | `birthday-portrait` | `birthday-portrait-v1` | 5 |
| Name Analysis | `name-analysis` | `name-analysis-v1` | 10 |

Shared invariants:

- Base URL: `https://api.numeroclaw.com`
- Authentication: `x-api-key: $NUMEROCLAW_API_KEY`
- New creation locale: `en-US`
- Create: `POST /api/v1/readings`
- Status: `GET /api/v1/readings/{readingId}`
- Result: `GET /api/v1/readings/{readingId}/result`
- Successful final content: `clientDocument`

If the fetched contract conflicts with this summary, follow the fetched contract and tell the user what changed.

## Choose the correct setup

### Codex

Add a concise `## NumeroClaw` section to the nearest applicable `AGENTS.md`. Do not modify global instructions unless the user explicitly requests a global installation.

### Claude Code or Claude Cowork

Add a concise `## NumeroClaw` section to the workspace `CLAUDE.md`. Preserve all existing content.

### OpenClaw

Create a workspace skill at `~/.openclaw/workspace/skills/numeroclaw/SKILL.md`, or the active equivalent. Declare `NUMEROCLAW_API_KEY` as a required environment variable and wire it through the skill configuration.

### Hermes

Create a NumeroClaw skill under `~/.hermes/skills/`. Declare `NUMEROCLAW_API_KEY` under `required_environment_variables` and store its value through the active Hermes secret setup.

### Another capable agent

Use its project-scoped instruction or skill mechanism. If none exists, create a local `NUMEROCLAW.md` runbook. Keep the key in the environment or secret store.

## Instructions to install

The persistent NumeroClaw instructions must tell the agent to:

1. Act only when the user explicitly asks for a NumeroClaw reading.
2. Identify the requested product. If unclear, ask before collecting data or spending credits.
3. Fetch the selected product catalogue and use its current input rules and credit cost.
4. Collect only the fields the product requires:
   - Theme: complete structured birth name, strict `YYYY-MM-DD` date of birth, and subject gender `M` or `F`.
   - Birthday Portrait: strict `YYYY-MM-DD` date of birth; first name is optional presentation data.
   - Name Analysis: complete structured birth name; current-use name is optional and requires contexts and scope when supplied. Do not ask for birth date or gender.
5. Show the normalized product, input, and exact catalogue credit cost. Obtain explicit confirmation immediately before creation.
6. Send the key through `x-api-key` without exposing it. Add a stable `Idempotency-Key` so retries cannot create duplicates.
7. Save the returned `readingId`. Poll status or use a webhook. NumeroClaw does not promise a fixed completion time.
8. Stop on `failed`. On `429`, respect `Retry-After`. On `402`, explain that more credits are required and do not retry blindly.
9. Retrieve `/result` only after completion and return `clientDocument` unchanged. Never invent or rewrite reading content.
10. Never create a reading merely to test the integration.

## Product request shapes

Theme:

```json
{
  "productId": "theme",
  "profileId": "evan",
  "locale": "en-US",
  "name": {
    "firstNames": ["Marie-France"],
    "middleNames": ["Paulette"],
    "lastNames": ["Dubois"]
  },
  "dateOfBirth": "1990-03-15",
  "grammaticalProfile": { "subjectGender": "F" }
}
```

Birthday Portrait:

```json
{
  "productId": "birthday-portrait",
  "profileId": "birthday-portrait-v1",
  "locale": "en-US",
  "dateOfBirth": "1990-03-15",
  "firstName": "Marie-France"
}
```

Name Analysis:

```json
{
  "productId": "name-analysis",
  "profileId": "name-analysis-v1",
  "locale": "en-US",
  "birthName": {
    "firstNames": ["Clara"],
    "middleNames": [],
    "lastNames": ["Moreau"]
  },
  "currentName": {
    "firstNames": ["Clara"],
    "middleNames": [],
    "lastNames": ["Martin"]
  },
  "currentNameContext": {
    "contexts": ["professional", "social"],
    "scope": "frequent",
    "usedSinceYear": 2018
  }
}
```

## Configure the secret

Check whether `NUMEROCLAW_API_KEY` is available without displaying its value.

- If present, report only that the secret is available.
- If missing, finish the non-secret setup and direct the user to **Developers → API keys** in the NumeroClaw portal.
- Do not claim the integration is ready to create readings until the secret is available.

## Verify without spending credits

- Confirm the instruction or skill file is discoverable.
- Confirm the API host can be reached if network access is available.
- Fetch one public catalogue resource to prove the API path.
- Confirm the environment variable name is configured without revealing its value.
- Do not send `POST /api/v1/readings`.

Finish with:

- detected environment
- what was configured and where
- whether the API key is available
- any network or permission limitation
- a sample next request: `Create a NumeroClaw Name Analysis`