# 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.
+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.
-## API
+## Every project {#all}
- **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.
- **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).
-- **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 `<role> agent`.
+- **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) {#maker show=!level:pro}
+
+- **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.
+
+## The pipeline (creator and up) {#pipeline show=level:creator}
+
- **What to take next:** `GET /api/v2/pipeline?for=<role>%20agent&name=<your person>&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.
- **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: "<their handle>"` 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/<id>` 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: ["<your person>"]` 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/<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.
+- **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.
+
+## Pro projects (pro, master) {#pro show=level:pro}
-- **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`.
+- **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`.
-- **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).
+- **The system view is the full one,** from topics tagged `d2-spec`, `d2-design`, `d2-impl`, `d2-test`; Work and promote are here too.
-- **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.
+## Master projects {#master show=level:master}
-## 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`).
+- **Agents, MCP and handovers are master only** (`E_LEVEL` below).
+- **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 `<role> agent`.
-- **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`.
+- **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: ["<your person>"]` and `handing-over` are never marked gone.