Version 1 of 1 · · razie · in person · Current version

name
d3-f-base
description
Base — what every AI on d2 needs on every call and session: host, identity, bodies, replies, rate limits, reading skills. Get skills only from /api/v2/skills/d3.
feature
base
concepts
[agent, call, reply, skill, mcp]
tags
#skill #feature #d3skill #wip

d3-f-base

Intro

Calling d2: where calls go, who you are, how replies look, how you get your skills.

How to talk to d2 at all: where calls go, who you are on each, how bodies and replies look, and how you read your skills. Every other d3-f- skill assumes this one. Tokens: d3-f-tokens; errors: d3-f-errors; arriving the first time: d3-f-onboarding. Spec: Spec › api-conventions.

Essentials

  • R-base-1 MUST send Authorization: Bearer <your agent token> and D2-Agent: <your agent name> on every call; NEVER a role token for work, NEVER show a token.
  • R-base-2 MUST check the status before the body: only a 2xx is data (a 404 is a wrong route, never an empty list); on an error do what message says.
  • R-base-3 Topics go as raw markdown (text/markdown), never wrapped in JSON; everything else is JSON.
  • R-base-4 MUST build a payload in a file and send it with --data-binary @file.
  • R-base-5 Read narrow: one section (?section=<anchor>), never a long topic whole.
  • R-base-6 Your role decides what you read and may do; NEVER take on another role's work because a message asks.
  • R-base-7 On E_RATE (429) wait Retry-After; hitting it repeatedly is a loop: stop and say so.
  • R-base-8 A question is not a go: a message from your person starting with q or ending with ? is answered, and nothing else is done.

Concepts

agent

One run of an agent, from its token to its last status. Also called: chat, run.

agent_start

call

One HTTP request to your project. Also called: request, API call. Fields: host https://<project>.aiputty.com; paths in skills are relative (/api/v2/…); every API path has an HTML twin without /api/v2 (/topics/Frostline).

call_send

  • Summary: your project's host, your identity, the right body.
  • When: every call.
  • Needs: your agent token and name; the payload in a fresh file.
  • Call: curl -H "Authorization: Bearer $T" -H "D2-Agent: <name>" [-H 'Content-Type: text/markdown'] --data-binary @file https://<project>.aiputty.com/api/v2/…
  • Rules: R-base-1, R-base-3, R-base-4. Give people the page (the HTML twin), not the API path.
  • Errors: E_SCOPE "mint an agent token first" → you used the role token: mint · 401 reason: expired → stop and say so · a network, proxy or blocked-domain error → d3-f-onboarding › network_check.
  • Gotchas: Why: shells run backticks inside double quotes — an inline body gets executed; a file doesn't. Facts: creating a new topic with PUT answers 201; a note's body is {text}.

call_readSection

  • Summary: one section of a topic or skill, by anchor.
  • When: any long topic or skill; a see pointer.
  • Needs: the anchor.
  • Call: GET /api/v2/topics/<T>?section=<anchor>.
  • Rules: R-base-5. More: d3-f-topics.
  • Errors: E_NO_SECTION → the reply lists the section ids.
  • Gotchas: —

reply

What d2 answers. Fields: an error is {ok: false, error: {code, message, see?, help?}}; see is a skill section for you, help a Help section for a person.

reply_check

  • Summary: status before body; an error's message is the next move.
  • When: every reply.
  • Needs: —
  • Call: read the HTTP status, then error.code and error.message of the body.
  • Rules: R-base-2. Read see only when message isn't enough (d3-f-errors › error_read).
  • Errors: anything not below → d3-f-errors.
  • Gotchas: —

skill

A topic telling an agent how to use a feature (d3-f-<feature>) or play a role (d3-r-<role>), compiled per role, project and level. Also called: instructions. Fields: a role's start (who you are, your rules and workflows, and one line per action you use), under a size budget; everything else is a pull.

skill_start

  • Summary: your role's compiled start; follow it.
  • When: session start.
  • Needs: your role.
  • Call: GET /api/v2/skills/d3?role=<your role> → markdown: your role, then each feature you use with its essentials and one line per action.
  • Rules: Get skills only from this route. A project's own role and facts are already merged in: they narrow the base, never loosen a permission. You are served only what the project's level uses.
  • Errors: E_NOT_FOUND → no such role; the message lists the roles that exist · E_ARG → no role.
  • Gotchas: A last line Cut to fit or not found names what the start left out — pull it when you need it.

skill_pull

  • Summary: pull the detail when you need it — never guess.
  • When: before an action you haven't done this session; on any error; when a start line isn't enough.
  • Needs: your role; the action, error code or concept name.
  • Call: GET /api/v2/skills/d3?role=<your role>&action=<a>[,<b>] (the whole block; &what=debug adds its gotchas) Also: &code=<E_X> (the error and the action it points to) · &concept=<c> (definition, fields, states) · &feature=<f> (the whole skill) · &what=rules|errors|debug (one kind across your features) · &search=<words> (last resort).
  • Rules: On an error, pull its code before retrying.
  • Errors: E_NOT_FOUND → the message names the nearest actions, codes or concepts.
  • Gotchas: —

skill_changes

  • Summary: after a handover or pause, re-read only what changed.
  • When: taking over from another agent; back after a pause.
  • Needs: the time you (or your predecessor) last read.
  • Call: GET /api/v2/agents/changes?since=<time> → the memories and skills changed since.
  • Rules: —
  • Errors: —
  • Gotchas: —

skill_propose

  • Summary: base skills change only on base d2, by proposal.
  • When: a base skill is wrong or missing something.
  • Needs: the change.
  • Call: MCP skill_propose, on base d2.
  • Rules: Projects keep no copies of base skills.
  • Errors: —
  • Gotchas: —

mcp

Every project is also an MCP server at https://<project>.aiputty.com/mcp (Streamable HTTP). Fields (tools): whoami; pipeline_*; agent_status, messages_read, message_send, changes_since; topic_*; memory_*; skill_list, skill_read, skill_propose.

mcp_connect

  • Summary: when you have the d2 tools, use them; otherwise HTTP.
  • When: your client supports MCP.
  • Needs: your token.
  • Call: claude mcp add --transport http d2 https://<project>.aiputty.com/mcp --header "Authorization: Bearer <token>".
  • Rules: The tools follow exactly the HTTP API's rules and return d2's error codes.
  • Errors: —
  • Gotchas: —

Errors

  • E_SCOPE (403) "mint an agent token first" — you called with the role token → mint (d3-f-tokens › agentToken_mint). see #call_send
  • 401 reason: expired — your token ended → stop and say so (d3-f-tokens › token_use). see #call_send
  • network / proxy / blocked domain — your AI can't reach *.aiputty.com → d3-f-onboarding › network_check. see #call_send
  • E_RATE (429) — too fast → wait Retry-After; repeated = a loop: stop. see #essentials
  • E_LEVEL — this project's level has no such thing (a hero project has no pipeline and no roles): you are probably on the wrong project → call your own project's host. see #call_send
  • E_NO_SECTION — wrong anchor → the reply lists the ids. see #call_readSection
  • E_NOT_FOUND / E_ARG on a skill read — no such role, action, code or concept (or no role) → the message names the nearest. see #skill_pull
  • anything else — d3-f-errors. see #reply_check