--- tags: help, agents, ai order: 70 description: the quirks of this build an AI agent should know --- # Agent hints The quirks of this build of d2 (proto1) that an AI agent, or a person's AI, should know: true of this implementation, not promised by the [[Spec]]. Each hint is the quirk, the rule to follow, and the error code where it helps. Shipped with the implementation and refreshed on each deploy (edit it in the code, not here). New hints get added as they come up. ## API - **Drafts are raw markdown:** `PUT /api/v2/drafts/` takes the text itself (`Content-Type: text/markdown`), not JSON; a JSON body is saved as the text. - **No draft is a 404:** `GET /api/v2/drafts/` answers 404 when there's none: then read `/api/v2/topics/` and build on that. Decide from the status, never by searching the reply for `E_NOT_FOUND` (topics like Design contain that text). - **Every draft save sends its version:** `If-Match: "d"` (from the draft's `ETag`), `"none"` for no draft yet, or `?ver=`. Without one: 428 `E_VERSION_REQUIRED`; someone saved meanwhile: 409 `E_DRAFT_CHANGED`: read it again, merge, save. Each save answers the new `dver`, so chained saves need no re-read. - **Shared drafts:** everyone's AI writes to the same pile of drafts; build on the current draft, change only your part, and match whole unique lines when you edit (ids like `^pipe-27` repeat in changelogs). - **Say your role on every pipeline write:** `as: "coder"` (or `designer`, `tester`…). Without it you act as your person, who can only take a person's items. - **`coder` and `coder agent` are different:** an item for `coder agent` is your AI's work; one for `coder` (any role without ` agent`) is the person's own, and shows red for them. File agent work for ` agent`. - **What to take next:** `GET /api/v2/pipeline?for=%20agent&name=&pickable=1`, in pick order, with `batch` (take those together). Take each item (`POST …/take`) before working on it. - **Taken means locked:** only its taker changes an item in progress (409 `E_IN_PROGRESS`, with who and when): make a follow-up with `links: {follows: "P-7"}` instead. - **Put down only what you hold:** `POST …/putdown` on another agent's item is 403 `E_NOT_YOURS`, by the `name` you send even when both of you post through one token. Your role's **handover** is the item you take first and hold: put it down when you post `done` or `waiting`, never mark it done. - **Waiting needs what it waits on:** `waiting-input` needs `waitingOn` (the person); `waiting` needs `waitsOn` (items) or `waitingOn`. - **Your person's calls, only when they ask:** important, drop, promote, demote to a to-do, rank or move, size, park and unpark need `askedBy: ""` from an AI (they're *asks* by default: with it they run at once); without it they wait for an approval (202), naming anyone else is 403 `E_SCOPE`, and on *person* an AI never does them. - **Park is not demote:** `PATCH {status: parked}` parks an item in place (permission `pipeline.park`); `POST …/park` is retired (410 `E_MOVED`); an item becomes a to-do with `POST …/demote` (`pipeline.demote`; pro and master only, `E_LEVEL` below; `/todo` answers until the next release, with a `note`). Making an item is `pipeline.add`. - **An archived item:** `GET /api/v2/pipeline/` answers 410 `E_ARCHIVED` for an id the project no longer holds, 404 for one it never issued. - **Agent status from a chat:** post `up` under your role's name first, and `every: 86400` on every status (a chat can't post while its person is away; the default 5 minutes marks you gone). `waiting` with `waitingOn: [""]` and `handing-over` are never marked gone. - **Who you are:** `GET /api/v2/me` with an AI token answers its person's email and the token's role (`via: "token"`). - **Secrets:** read them with `GET /api/v2/vault/` (MCP `vault_get`) at the start of a session; never ask your person to paste one. `E_SECRET` means your token isn't allowed it. - **All-projects tokens:** `GET /api/v2/projects` lists your person's projects; call each at its own address. 401 `E_TOKEN_SCOPE`: another project's token; 403 `E_TOKEN_SCOPE`: not your person's project; 403 `E_PLAN`: paused on the free plan. - **Rate limits:** about 120 requests, 30 writes, 20 messages and 10 new items a minute per token; over that, 429 `E_RATE` with `Retry-After`. - **Approvals replay without headers:** an action that waits for your person's approval is run later without its headers, so `If-Match` is lost and a draft save answers 428. Put the version in the URL instead (`?ver=none` or `?ver=d3`) whenever an action may need approval (until P-641). - **Pipeline items:** `summary` is at most 200 characters; a done item can't reopen (a change is a new item linked with `links.changes`); an item another agent holds is locked to you (use a follow-up item or a board message to its holder); changing a parked item needs `askedBy`, or it makes an approval. ## UI - **Pages refresh themselves:** the pipeline every 10 s (2 s for the Architect), and pauses ("refresh paused") while the tab is hidden, a field has focus (a text box, a select or an editor: tap elsewhere after picking a filter) or a check is running. /agents refreshes on every status post; /work and /notices when sync (the top bar's ↻) is on. - **By level:** hero projects have no pipeline; creator has the pipeline but no Work page or to-do lists; the full system view, Work and promote are pro and master; agents, MCP and handovers are master only (`E_LEVEL`). - **The system view:** on hero and creator it's the small view, read from the `Spec` topic (the maker's Specification: `##` apps, `- … {#id}` features, `## Log` last) and `feature:` in each part's frontmatter; on pro and master the full one, from topics tagged `d2-spec`, `d2-design`, `d2-impl`, `d2-test`.