Version 9 of 11 · · razie via designer-28administrator · Current version

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. Grouped by the project's level: the hints for every project first, then the ones for your project's level (the sections you don't need aren't shown). Edited here, on base d2; new hints get added as they come up.

Every project

  • Drafts are raw markdown: PUT /api/v2/drafts/<topic> 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/<topic> answers 404 when there's none: then read /api/v2/topics/<topic> 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<n>" (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).
  • 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/<name> (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).
  • 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).

Maker projects (hero, creator)

  • Hero has no pipeline; creator has the pipeline with your maker agent, but no Work page or to-do lists.
  • The system view is the small one, read from the Spec topic (the maker's Specification: ## apps, - … {#id} features, ## Log last) and feature: in each part's frontmatter.