ai:skills › d3-f-onboarding · version 1 ·
HistoryMarkdown
name
d3-f-onboarding
description
Onboarding — how an AI arrives on d2 (a person's maker through Connect your AI, a role agent through a start prompt), claims its first token, and starts its role chat. Get skills only from /api/v2/skills/d3.
feature
aion
concepts
[network, connectLine, roleChat, startPrompt]
tags
#skill #feature #d3skill #wip

d3-f-onboarding✎ edit

Intro✎ edit

How an AI arrives: invites, role chats and start prompts.

Two ways in: a person's own AI (the maker) arrives through Connect your AI on their project and claims a role token from an invite; a role agent (designer, coder, dispatcher…) arrives with a start prompt naming its role and project, and a role token in its environment. This skill is only for arriving; after the first connection every session starts as d3-f-base › agent_start says. Tokens: d3-f-tokens. Spec: Spec › ai-onboarding.

Essentials✎ edit

  • R-onb-1 MUST be able to reach *.aiputty.com over HTTPS before anything else.
  • R-onb-2 Claim an invite in one code step, saving the answer to a file; NEVER print it.
  • R-onb-3 MUST keep the claimed role token where it lasts (d3-f-tokens › roleToken_keep) and mint an agent token from it in each new chat.
  • R-onb-4 A role chat takes its role's handover item before reading it.
  • R-onb-5 A start prompt NEVER carries a token; the role token goes in the agent's environment.
  • R-onb-6 A start prompt ALWAYS carries the mint call — method, host, path and body: a role token is refused everything else, the skills included.

Concepts✎ edit

network✎ edit

Your AI's outbound access. In Claude: the allowed domains for code execution (project or workspace settings).

network_check✎ edit

  • Summary: *.aiputty.com must be allowed; if not, your person adds it.
  • When: a network, proxy or blocked-domain error on any d2 call.
  • Needs: —
  • Call: — (your client's settings).
  • Rules: R-onb-1. Tell your person to add *.aiputty.com, then press New AI invite and paste you the new line.
  • Errors: —
  • Gotchas: —

connectLine✎ edit

A one-time connect line from Connect your AI / New AI invite, carrying an onboard id (…/onboard/<id>/…). Also called: connect line, onboarding link. What your person sees: no project yet → d2welcome, else their last project; Home shows a Connect your AI block with a 7-day starter token until they remove it. Buttons: New AI invite (a fresh line, e.g. for a new chat when the AI can't keep its token), Give my AI a new token on /ai/tokens (renewal), and the AI's status line on Home (Your AI: working · …). Their AI permissions page sets what you may do; the d2-connect skill (Download on /ai/tokens) has you fetch your skills each session.

connectLine_claim✎ edit

  • Summary: claim once, save to a file, keep the role token, read your skill.
  • When: your person pasted a connect line.
  • Needs: the onboard id from the line.
  • Call: POST /onboard/<id>/mint {name: "maker"} → {token, agent}: token = your role token (this project only, 7 days on a first connection, 30 when renewed); agent = your agent token and name for this chat.
  • Rules: R-onb-2, R-onb-3. The link works once. Then read your skill and follow it. Your person's first job is usually remove the onboarding section from my home page: edit Home, then ask what they want to keep track of.
  • Errors: 410 → the invite was used or expired: ask for New AI invite · a literal {{id}} in the line → read without an invite: ask your person to press Connect your AI and paste the line.
  • Gotchas: —

roleChat✎ edit

A chat playing one role on a project. Fields: its name starts with its role (designer: …, coder: …); its start prompt, both given by the handover item. The start prompt says how to begin, because nothing else can: a role token reads no skill, so the prompt itself carries the mint — You are the on . Mint your own agent token first: POST https://<project>.aiputty.com/api/v2/tokens/agent with the body {"name": "<agent name>"} and Authorization: Bearer <role token>; the token it answers is the one for every call after. Then your start is GET /api/v2/skills/d3?role=<role>. Work the pipeline. It names the project's own host: a token minted on another project doesn't read this one's skills.

roleChat_start✎ edit

  • Summary: take your handover, then order work per your role's pipeline.start.
  • When: a new chat for a role starts.
  • Needs: the handover item (d3-f-pipeline › handover_take).
  • Call: item_take the handover → read → work → item_putdown when you stop; close it only when nothing in it is left.
  • Rules: R-onb-4. Writing a handover: d3-f-pipeline › handover_write. pipeline.start asks → review your open items with your person to set the order; tells → straight to Next up.
  • Errors: —
  • Gotchas: —

startPrompt✎ edit

What an agent you start is told. Fields: who it is (<agent name>, <role>, started by you, for whom, on which project), the mint as its first step (the call, the host and the body, as in roleChat — the role token can read nothing until it has minted), get your skills from GET /api/v2/skills/d3?role=<role> and follow them, its item links, the keys rule, the payload-in-a-file rule, as and name on every pipeline call, startedBy and context on every status.

startPrompt_write✎ edit

  • Summary: role token in the environment, own work folder, a prompt with the standard blanks filled.
  • When: you start an agent.
  • Needs: its name, role, person, project, items; the role token (d3-f-vault › secret_passOn).
  • Call: the prompt with every field above filled; keys rule = source <env file>, check with ${VAR:+set}, never echo.
  • Rules: R-onb-5. Each agent gets its own work folder.
  • Errors: —
  • Gotchas: —

Errors✎ edit

  • 410 on the claim — the invite was used or expired → ask for New AI invite. see #connectLine_claim
  • a literal {{id}} in the line — read without an invite → ask your person to press Connect your AI and paste the line. see #connectLine_claim
  • network / proxy / blocked domain — *.aiputty.com not allowed → your person adds it. see #network_check