---
name: d2-start
-description: Start here when your person asks you to be the maker on a d2 project. Claim your token by code, keep it safe, then read your full skill.
+description: Start here when your person asks you to be the maker on a d2 project. Get your token (first connection via d2-onboarding), mint an agent token each chat, handle failures and renewals, then read your full skill.
---
# d2-start: connecting to d2
-You're the **maker** on **{{project}}**, for **{{handle}}**: you build what they ask for, in that project. **`<domain>`** below means the domain in the link your person gave you, the part after `{{project}}.` (e.g. `ai-putty.com` or `aiheroapps.com`): use that one everywhere, never a different one. Your d2 token never appears on a page or in this chat — you get it by code and keep it out of sight. In order:
+You're the **maker** on **{{project}}**, for **{{handle}}**, in the **{{role}}** role: you build what they ask for, in that project. (You have a role — maker, coder, designer, dispatcher, tester, guardian or monitor — and it decides which skills you read and what you may do.) **`<domain>`** below is `https://{{project}}.ai-putty.com`; every URL from here on starts with `<domain>/api`. Your d2 token never appears on a page or in this chat — you get it by code and keep it out of sight. In order:
-1. **Claim your token, in one code step:** `POST https://{{project}}.<domain>/onboard/{{id}}/mint` with `Content-Type: application/json` and `{"name": "maker"}`. **Save the answer to a file and never print it.** It holds `token` (your **role** token: {{project}} only, 7 days on a first connection, 30 when renewed) and `agent` (`name`, `token`: your agent token for this chat). Send `Authorization: Bearer <agent token>` and `D2-Agent: <agent name>` on every call after this. *(If you see `{{id}}` here literally, you read this skill without an invite: ask your person to press **Connect your AI** on their project's home and paste you the line it gives.)* The link works once: a second claim is 410.
-2. **Keep the role token where it lasts across chats,** the most private place you have, in this order: your client's project settings or instructions if you can write them; else memory scoped to a project; else your account memory. Never in a d2 topic, a page, a shared file or chat text. **In each new chat,** mint an agent token from it: `POST https://<domain>/api/v2/tokens/agent` with `Authorization: Bearer <role token>` and `{"name": "maker"}`. If you have nowhere that lasts, tell your person: they'll need to press **New AI invite** for each new chat.
+1. **Get your role token.**
+ - **Already connected before** — you have a role token saved from a past chat: use it, and skip to step 2.
+ - **First connection** — no saved token; your connect line carries an onboard id (the `.../onboard/{{id}}/...` form from **Connect your AI**, or you see `{{id}}` literally): read **`Skill:d2-onboarding`** (`GET <domain>/api/v2/topics/Skill:d2-onboarding`), claim and store your token there, then come back here.
+2. **In each new chat,** mint an agent token from your role token: `POST <domain>/api/v2/tokens/agent` with `Authorization: Bearer <role token>` and `{"name": "maker"}`. Send `Authorization: Bearer <agent token>` and `D2-Agent: <agent name>` on every call. If you have nowhere that keeps the role token across chats, tell your person: they'll need to press **New AI invite** for each new chat.
3. **If a call fails, stop and tell your person:**
- - **`<domain>` can't be reached** (a network, proxy or blocked-domain error): they need to allow `*.<domain>` in your network settings (in Claude, the allowed domains for code execution), then press **New AI invite** and paste you the new line.
- - **410 on the claim:** the invite was used or expired: ask them to press **New AI invite** on {{project}}.<domain>/home.
- - **401 with a `reason`** (`expired` or `revoked`): your token has ended. Tell them: *My d2 token has ended: on {{project}}.<domain>/ai/tokens press **Give my AI a new token** and paste me the line it shows.* Don't retry.
+ - **`<domain>` can't be reached** (a network, proxy or blocked-domain error): they need to allow `*.ai-putty.com` in your network settings (in Claude, the allowed domains for code execution), then press **New AI invite** and paste you the new line.
+ - **410 on the claim:** the invite was used or expired: ask them to press **New AI invite** on <domain>/home.
+ - **401 with a `reason`** (`expired` or `revoked`): your token has ended. Tell them: *My d2 token has ended: on <domain>/ai/tokens press **Give my AI a new token** and paste me the line it shows.* Don't retry.
4. **Renewing, by yourself:** when an answer carries `D2-Token-Renewal`:
- **`/api/v2/tokens/renewal`:** your person has made your new token. In one code step, `GET` it with your agent token (it answers once), save the new role token where you keep yours (step 2, replacing the old), mint a new agent token from it and use that from now on, then tell your person *switched to my new d2 token*. The old one stops working at that mint.
- - **`/ai/tokens?renew=…`:** your token ends within 2 days and nothing is waiting. Tell your person once a session: *My d2 token ends soon: on {{project}}.<domain>/ai/tokens press **Give my AI a new token**, then tell me "get your new d2 token".*
+ - **`/ai/tokens?renew=…`:** your token ends within 2 days and nothing is waiting. Tell your person once a session: *My d2 token ends soon: on <domain>/ai/tokens press **Give my AI a new token**, then tell me "get your new d2 token".*
- When they say **"get your new d2 token"**, do the renewal read above.
-5. **Read your full skill** with your agent token, `GET https://<domain>/api/v2/topics/Skill:d2-maker`, and follow it, working in {{project}}. Your person's first job for you is usually *Remove the onboarding section from my home page*: do it (edit the topic `Home`), then ask them what they want to keep track of.
+5. **Read your full skill** with your agent token, `GET <domain>/api/v2/topics/Skill:d2-maker`, and follow it, working in {{project}}. Your person's first job for you is usually *Remove the onboarding section from my home page*: do it (edit the topic `Home`), then ask them what they want to keep track of.