HistorySkill:d2-maker

Up to 100 versions are kept, as small diffs with a full copy every 10th. Restore makes a new version with the old text: nothing is lost.

• version 22current 2026-10-05 11:43 UTC · razie · in person ViewText
• version 21diff 2026-10-05 03:57 UTC · razie · in person ViewText
  What version 22 changed

  …

  description: Build on a d2 project at <project>.aiheroapps.com from an AI assistant, as its maker: model the data, build the pages and apps, fill in data, keep the project's Specification, report your status and hand over. Everything any AI needs on d2, fitted to the project's level. Fetched by d2-connect with GET /api/v2/skills; use whenever the person mentions d2 or their d2 project.

  core: [install, calls, working-with-your-person, topics-you-cant-see, new-topics, topics-and-categories, things-to-know]

  +tags: inherited

  ---

   

  …
• version 20full copy 2026-10-05 01:14 UTC · razie · in person ViewText
  What version 21 changed

  ---

  name: d2-maker

  -description: Build on a d2 project at <project>.aiheroapps.com from an AI assistant, as its maker: model the data, build the pages and apps, fill in data, write rules and stories, keep the project's Specification, report your status and hand over. Everything any AI needs on d2, fitted to the project's level. Fetched by d2-connect with GET /api/v2/skills; use whenever the person mentions d2 or their d2 project.

  +description: Build on a d2 project at <project>.aiheroapps.com from an AI assistant, as its maker: model the data, build the pages and apps, fill in data, keep the project's Specification, report your status and hand over. Everything any AI needs on d2, fitted to the project's level. Fetched by d2-connect with GET /api/v2/skills; use whenever the person mentions d2 or their d2 project.

  core: [install, calls, working-with-your-person, topics-you-cant-see, new-topics, topics-and-categories, things-to-know]

  ---

  …
• version 19diff 2026-10-04 12:45 UTC · razie · in person ViewText
  What version 20 changed

  …

  # d2-maker: building on d2 from your AI

   

  -You are the project's **maker**: you model the data, build the pages, fill in data and fix what breaks, all from your person's chat. d2 is a wiki, a domain model and an object store behind one HTTP API. Every project has its own address, `https://<project>.aiheroapps.com/api/v2`, and its own topics and objects; the demo is `https://d2pro.aiheroapps.com/api/v2`. (Addresses under the old name, `aidieselapps.com`, redirect there.) Work on your person's project at its own address (the examples below use the `d2pro` demo). Everything here uses plain HTTP, so any assistant that can make web requests can use it.

  +You are the project's **maker**: you model the data, build the pages, fill in data and fix what breaks, all from your person's chat. d2 is a wiki, a domain model and an object store behind one HTTP API. Every project has its own address, `https://<project>.aiheroapps.com/api/v2`, and its own topics and objects; the demo is `https://d2pro.ai-putty.com/api/v2`. (Addresses under the old name, `aidieselapps.com`, redirect there.) Work on your person's project at its own address (the examples below use the `d2pro` demo). Everything here uses plain HTTP, so any assistant that can make web requests can use it.

   

  ## Your project's level

  …

   

  ```bash

  -B=https://d2pro.aiheroapps.com/api/v2

  +B=https://d2pro.ai-putty.com/api/v2

  curl -s $B/health # version, topic count

   

  …

  - A topic id is `Category:name`, or just `name` for an ordinary wiki topic. The categories are `Topic`, `Spec`, `Memory`, `Skill`, `Style`, `Log`, `AiLog`, `AiSpec`, `OpenSpec`, `OpenSpecChange`, `ToDo`, `Story` and `Settings`.

  - Names use letters, digits, `-` and `_`, with no spaces.

  -- A `PUT` replaces the whole topic, so read it first, change it, and write it back. The reply has `ver`, plus `errors` (markdown and declaration problems), `domain` (model checks for classes in this topic) and `objects` (objects that failed to load). If any of those are non-empty, fix the topic and write it again before telling the user it's done.

  +- A `PUT` replaces the whole topic, so read it first, change it, and write it back. **The request body is the raw markdown of the topic — send it directly (the markdown text as the body), not wrapped in a JSON object like `{"body": "…"}`. d2 stores the request body verbatim, so a JSON wrapper gets saved as the topic's content and the page then shows the literal JSON instead of your markdown.** The reply has `ver`, plus `errors` (markdown and declaration problems), `domain` (model checks for classes in this topic) and `objects` (objects that failed to load). If any of those are non-empty, fix the topic and write it again before telling the user it's done.

  - Links: `[[Topic]]`, `[[Memory:name]]`, `[[Skill:name]]`, `[[Class:key]]` for an object, `[[target|label]]` for your own text, and `[[otherproject.Topic:Notes]]` for a topic in another project. A section: `[[Topic#Heading]]` or `[[#Heading]]` on the same page (a heading's id is GitHub's slug of it, or its own `{#id}`; a link to a missing section shows as broken). To read one section instead of a whole long topic: `GET /api/v2/topics/<name>?section=<id>` (a 404 lists the topic's section ids).

   

  …

   

  - **Build one** from what the user says: write the `Spec:` topic, add a few sample objects so they can see it working, and tell them where to look (`/dom/<Class>`). **If ESP (Mind Meld) is on** — `GET /api/v2/esp/here` returns a tab rather than `404 E_ESP_OFF` — take them straight there with `POST /api/v2/esp/go {url, why}` (the app's page or `/dom/<Class>`, `why` like "your new book club") so they land on what you just built instead of hunting for it. If ESP is off, just give the link.

  -- **Import an example**: examples live in their own projects (today `d2portfolio`: `Spec:portfolio` and `Story:portfolio-samples`). Read each topic from the example (`GET https://d2portfolio.aiheroapps.com/api/v2/topics/Spec:portfolio`) and write it into the user's project under the same name. If the user has data of their own, offer to put it in place of the samples.

  +- **Import an example**: examples live in their own projects (today `d2portfolio`: `Spec:portfolio` and `Story:portfolio-samples`). Read each topic from the example (`GET https://d2portfolio.ai-putty.com/api/v2/topics/Spec:portfolio`) and write it into the user's project under the same name. If the user has data of their own, offer to put it in place of the samples.

  - **Then add a card for it at the top of `Home`** (Razie, 2026-09-25). A home page's app cards are the first ```` ```cards ```` block right after its `# ` title. If the page has none there, start one: a new block directly under the title line. Add one line per app, keep the ones already there, and don't add a second card for the same app:

   

  …
• version 18diff 2026-10-03 20:50 UTC · razie · in person ViewText
  What version 19 changed

  …

  - Names use letters, digits, `-` and `_`, with no spaces.

  - A `PUT` replaces the whole topic, so read it first, change it, and write it back. The reply has `ver`, plus `errors` (markdown and declaration problems), `domain` (model checks for classes in this topic) and `objects` (objects that failed to load). If any of those are non-empty, fix the topic and write it again before telling the user it's done.

  -- Links: `[[Topic]]`, `[[Memory:name]]`, `[[Skill:name]]`, `[[Class:key]]` for an object, `[[target|label]]` for your own text, and `[[metals.Topic:Spec]]` for a topic on a d1 reactor. A section: `[[Topic#Heading]]` or `[[#Heading]]` on the same page (a heading's id is GitHub's slug of it, or its own `{#id}`; a link to a missing section shows as broken). To read one section instead of a whole long topic: `GET /api/v2/topics/<name>?section=<id>` (a 404 lists the topic's section ids).

  +- Links: `[[Topic]]`, `[[Memory:name]]`, `[[Skill:name]]`, `[[Class:key]]` for an object, `[[target|label]]` for your own text, and `[[otherproject.Topic:Notes]]` for a topic in another project. A section: `[[Topic#Heading]]` or `[[#Heading]]` on the same page (a heading's id is GitHub's slug of it, or its own `{#id}`; a link to a missing section shows as broken). To read one section instead of a whole long topic: `GET /api/v2/topics/<name>?section=<id>` (a 404 lists the topic's section ids).

   

  ## Tags

  …

  - Errors look like `{ok: false, error: {code, message}}`. Codes include `E_AUTH` (missing or wrong token), `E_NOT_FOUND`, `E_VALIDATION`, `E_EXISTS` and `E_PARSE`.

   

  -Related: [[Skill:d2-agents]] (master roles), [[Skill:company-notes]], [[Skill:domain-modelling]], and the pattern this comes from, [[metals.Topic:AiSpec|AiSpec]].

  +Related: [[Skill:d2-agents]] (master roles), [[Skill:company-notes]], [[Skill:domain-modelling]].

   

  ## Changelog

  …
• version 17diff 2026-10-03 18:52 UTC · razie · in person ViewText
  What version 18 changed

  …

  An app is a model (a `Spec:` topic with `$class` lines), its data (objects, often seeded from a `Story:` topic with `$object` lines) and a way in from the project's home page.

   

  -- **Build one** from what the user says: write the `Spec:` topic, add a few sample objects so they can see it working, and tell them where to look (`/dom/<Class>`).

  +- **Build one** from what the user says: write the `Spec:` topic, add a few sample objects so they can see it working, and tell them where to look (`/dom/<Class>`). **If ESP (Mind Meld) is on** — `GET /api/v2/esp/here` returns a tab rather than `404 E_ESP_OFF` — take them straight there with `POST /api/v2/esp/go {url, why}` (the app's page or `/dom/<Class>`, `why` like "your new book club") so they land on what you just built instead of hunting for it. If ESP is off, just give the link.

  - **Import an example**: examples live in their own projects (today `d2portfolio`: `Spec:portfolio` and `Story:portfolio-samples`). Read each topic from the example (`GET https://d2portfolio.aiheroapps.com/api/v2/topics/Spec:portfolio`) and write it into the user's project under the same name. If the user has data of their own, offer to put it in place of the samples.

  - **Then add a card for it at the top of `Home`** (Razie, 2026-09-25). A home page's app cards are the first ```` ```cards ```` block right after its `# ` title. If the page has none there, start one: a new block directly under the title line. Add one line per app, keep the ones already there, and don't add a second card for the same app:

  …

  Related: [[Skill:d2-agents]] (master roles), [[Skill:company-notes]], [[Skill:domain-modelling]], and the pattern this comes from, [[metals.Topic:AiSpec|AiSpec]].

   

  +## Changelog

  + 

  +- 2026-10-03 — After building/importing an app, if ESP is on, navigate the user to it with `esp/go` instead of only giving a link. (Razie)

  + 
• version 16diff 2026-10-03 10:34 UTC · razie · in person ViewText
  What version 17 changed

  …

  - **Post notices after the write:** say something is done only after the write it's about has returned.

   

  +## ESP (Mind Meld): show your person the page {lookup}

  + 

  +Your person can turn on **ESP** (also called Mind Meld) in a browser tab: the ESP button at the top, right of the sync button. While it's on, you can see which page they're looking at and take that tab to the page you're talking about. It only moves the tab. You can't click, type or approve anything in it. Help for people: [[d2.Help:ESP]].

  + 

  +- **Before you say "this page", ask where they are:** `GET /api/v2/esp/here` returns `{url, section, title}` of their ESP tab. `404 E_ESP_OFF` means no tab of theirs has ESP on. A 404 without that code means this d2 doesn't have ESP yet. In both cases give links instead, as usual.

  +- **Take them to a page while you talk about it:** `POST /api/v2/esp/go {url, section?, why}`. `url` is a path on this project or a full URL on another of their d2 projects; `section` is the anchor; `why` is one short line they'll read in the toast ("the rules we're changing"). The answer is `{id, tab, mode}`. Their tab moves within about 2 s and offers them Back.

  +- **They decide how much you may do:** the permission `agents.esp` on their AI permissions page. `person` gets you `E_SCOPE` (give links instead), `asks` shows them a Go button (check `GET /api/v2/esp/go/<id>`), `tells` and `free` move the tab.

  +- **"Switch to ESP" / "mind meld":** `POST /api/v2/esp/on {why}` asks their ESP tab to turn it on. Unless they set `agents.espOn` to free, they get a small bar to tap. You can always turn it off: `POST /api/v2/esp/off`.

  +- **Be a good guest:** move them only to show what you're talking about, at most once every few seconds (`E_RATE`). Never move them while they're reading something you asked them to read, and never loop. Tell them in the chat where you took them, with the link too. When you've just written a draft, take them to it: ESP turns sync on, so they see your draft, not the published text.

  + 

  ## The Specification: what you built, in the person's words (hero and creator)

   

  …
• version 15diff 2026-10-01 03:44 UTC ViewText
  What version 16 changed

  …

   

  1. **Network.** Let your AI reach `aiheroapps.com` over HTTPS. In Claude, allow the domains in the network settings of your project or workspace (`aiheroapps.com` and `*.aiheroapps.com` cover them).

  -2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **Settings** → **AI permissions** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one. A token has a **kind**: a **role** token is an AI's, and an AI on a master project mints one short-lived token of its own per run from it (`POST /api/v2/tokens/agent {name}`); a **tool** token is a program's and is used directly. Either works as it always did.

  +2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **Settings** → **AI permissions** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Keep your role token where it lasts across chats, the most private place you have: your client's project settings or instructions if you can write them, else project-scoped memory, else account memory; never in a topic, a page, a shared file, this skill or chat text, and never print it. In each new chat mint an agent token from it. If a call comes back 401 with a `reason`, your token has ended or was revoked: tell your person to press **Give my AI a new token** on <project>.aiheroapps.com/ai/tokens and paste you the line it shows; don't retry. **Renewing:** when an answer carries `D2-Token-Renewal: /api/v2/tokens/renewal`, your person has made your new token: in one code step `GET` it with your agent token (it answers once), save the new role token in place of the old, mint a new agent token from it, and tell them *switched to my new d2 token* (the old one stops at that mint). When the header points at `/ai/tokens?renew=…`, your token ends within 2 days: tell them once a session *My d2 token ends soon: on <project>.aiheroapps.com/ai/tokens (user menu → Settings → AI permissions → AI tokens) press **Give my AI a new token**, then tell me "get your new d2 token".* When they say it, do the renewal read. A token has a **kind**: a **role** token is an AI's, and an AI on a master project mints one short-lived token of its own per run from it (`POST /api/v2/tokens/agent {name}`); a **tool** token is a program's and is used directly. Either works as it always did.

  **Drafts.** Most tokens write **drafts**: a `PUT` to a topic answers `{"draft": true}` and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their **Drafts** page (`/drafts`, the Drafts button in the top bar), where they see the diff and publish it. `GET /api/v2/drafts` lists the drafts, `GET /api/v2/drafts/<topic>` gives one; read your own draft, not the published topic, when you continue work on something you drafted.

  **Drafts are shared.** All of one person's AIs (designer, coder, any agent) write into the *same* draft of a topic, so before any edit `GET /api/v2/drafts/<topic>`: if there is one, build on it and change only your part; starting from the published text when a draft exists silently erases another agent's pending work. A **404** from that call means no draft: then read `GET /api/v2/topics/<topic>` and build on that. Decide by the HTTP status, never by searching the reply for `E_NOT_FOUND` (topics like Design contain that text). **Every save says which version it built on** (P-103): the draft `GET` gives `ETag: "d<n>"` (and `dver`; a 404 gives `"none"`), and your `PUT` sends it back as `If-Match: "d<n>"` or `"none"`, or `?ver=d<n>` / `?ver=none`. Without it you get `428 E_VERSION_REQUIRED`; if the draft moved on since you read it, `409 E_DRAFT_CHANGED` (who saved it, and the new `dver`) and nothing is written: re-read, merge your change into it, and save again. Each `PUT` answers the new `dver`, so several saves in a row chain without re-reading. A draft or topic `PUT` takes the **raw markdown** with `Content-Type: text/markdown`; a JSON body (`{"content": …}`) is saved as the topic's text, so read the draft back once after a first write if unsure. When inserting, match a whole unique line: ids like `^pipe-27` also appear in changelog lines, so a bare id can match twice. After editing, leave a note (on your pipeline item, or an Agents board message) naming the topics and sections you touched, so another agent checks those spots before its next edit; re-read a draft before editing only when someone else has touched it since your last read. Objects aren't drafts: writes to objects are live. Deleting a topic isn't possible with a drafts token: ask the user.

  …

  - Watering reminders {#garden-water}

   

  -## Log

  - 

  -- 2026-09-28: asked for watering reminders; built Rule:watering and Story:watering

  -- 2026-09-27: asked for a garden planner; built App:garden

  ```

   

  - **A `##` heading per app** or thing the person asked for, with its `{#id}` and one line of what they asked; **a line per feature** under it, with its `{#id}` (`Title: what it does` or just the words).

  -- **`## Log` at the bottom:** a dated line per change, newest first: what was asked, what you built or changed. There's no `Log:PROJECT` on maker projects: this is the log. d2 adds a line itself when the project is released.

  +- **Record each change in the history:** `POST /api/v2/history {type: "ai", text}` — what was asked, what you built or changed; the person sees it as the project's log (`Log:PROJECT`). The Specification has no `## Log` section any more.

  - **`feature: <id>` on what you make:** in the frontmatter of each page, app, rules topic or other part that makes the feature work (`features: a, b` for several). That's what makes the row *built*.

  - **A story per feature:** a `Story:` topic with the same `feature: <id>`, run after a change; its last run makes the row *checked* (or *fails*, with a **Fix it** for you).

  …

  Related: [[Skill:d2-agents]] (master roles), [[Skill:company-notes]], [[Skill:domain-modelling]], and the pattern this comes from, [[metals.Topic:AiSpec|AiSpec]].

   

  -## Changelog

  - 

  -- 2026-10-01: **tokens have a kind** (P-489): **role** (an AI's, which mints one short-lived token per run), **tool** (a program's, used directly) and **agent** (minted, never made on the page). A token made before this is a role token and keeps working exactly as it did.

  -- 2026-09-30: times you tell a person are in **the user's** local time zone, never UTC in prose (P-367); the zone is on the account and comes back from `GET /api/v2/me` as `tz` (IANA, `null` when unset). What machines read stays ISO 8601 UTC.

  -- 2026-09-30: an item's `summary` (P-447): one sentence, at most 200 characters, on `POST /api/v2/pipeline` and `PATCH /api/v2/pipeline/<id>` (`""` clears it); write one on every item you file, or the item's page shows the document's first sentence instead.

  -- 2026-09-29: read lean (P-345): the pipeline list leaves `doc` out and takes `fields`, `forRole`, `forName` and `status=open`; the board takes `since` (a message id too) and `limit`; a topic's section is read *and written* by its anchor.

  -- 2026-09-29: a project's own process is `Skill:process`, served after the base skills; no copies of base skills (P-302).

  -- 2026-09-29: frontmatter `core:` lists the sections served as d2-core to the specialist roles on master (P-276).

  -- 2026-09-29: the user makes tokens and keeps secrets under Settings → AI permissions (`/ai`, P-271).

  -- 2026-09-29: many objects: use `/api/v2/dom/batch` (P-257).

  -- 2026-09-29: tables are drawn with the page (reload for new data); the class `?stamp=1` is gone (P-236).

  -- 2026-09-28: tables redraw by themselves when their data changes; `?stamp=1` on a class (P-201).

  -- 2026-09-28: permissions: *person* is your person themself only; *asks* runs at once with askedBy (P-176).

  -- 2026-09-28: split out of `Skill:diesel2` (P-146): what every AI needs to build on d2; the level line; the pipeline lightly (park, take your own, close); the role work moved to `d2-agents`. Served by `GET /api/v2/skills`.

  - 
• version 14diff 2026-09-30 16:09 UTC ViewText
  What version 15 changed

  …

   

  1. **Network.** Let your AI reach `aiheroapps.com` over HTTPS. In Claude, allow the domains in the network settings of your project or workspace (`aiheroapps.com` and `*.aiheroapps.com` cover them).

  -2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **Settings** → **AI permissions** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one.

  +2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **Settings** → **AI permissions** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one. A token has a **kind**: a **role** token is an AI's, and an AI on a master project mints one short-lived token of its own per run from it (`POST /api/v2/tokens/agent {name}`); a **tool** token is a program's and is used directly. Either works as it always did.

  **Drafts.** Most tokens write **drafts**: a `PUT` to a topic answers `{"draft": true}` and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their **Drafts** page (`/drafts`, the Drafts button in the top bar), where they see the diff and publish it. `GET /api/v2/drafts` lists the drafts, `GET /api/v2/drafts/<topic>` gives one; read your own draft, not the published topic, when you continue work on something you drafted.

  **Drafts are shared.** All of one person's AIs (designer, coder, any agent) write into the *same* draft of a topic, so before any edit `GET /api/v2/drafts/<topic>`: if there is one, build on it and change only your part; starting from the published text when a draft exists silently erases another agent's pending work. A **404** from that call means no draft: then read `GET /api/v2/topics/<topic>` and build on that. Decide by the HTTP status, never by searching the reply for `E_NOT_FOUND` (topics like Design contain that text). **Every save says which version it built on** (P-103): the draft `GET` gives `ETag: "d<n>"` (and `dver`; a 404 gives `"none"`), and your `PUT` sends it back as `If-Match: "d<n>"` or `"none"`, or `?ver=d<n>` / `?ver=none`. Without it you get `428 E_VERSION_REQUIRED`; if the draft moved on since you read it, `409 E_DRAFT_CHANGED` (who saved it, and the new `dver`) and nothing is written: re-read, merge your change into it, and save again. Each `PUT` answers the new `dver`, so several saves in a row chain without re-reading. A draft or topic `PUT` takes the **raw markdown** with `Content-Type: text/markdown`; a JSON body (`{"content": …}`) is saved as the topic's text, so read the draft back once after a first write if unsure. When inserting, match a whole unique line: ids like `^pipe-27` also appear in changelog lines, so a bare id can match twice. After editing, leave a note (on your pipeline item, or an Agents board message) naming the topics and sections you touched, so another agent checks those spots before its next edit; re-read a draft before editing only when someone else has touched it since your last read. Objects aren't drafts: writes to objects are live. Deleting a topic isn't possible with a drafts token: ask the user.

  …

  ## Changelog

   

  +- 2026-10-01: **tokens have a kind** (P-489): **role** (an AI's, which mints one short-lived token per run), **tool** (a program's, used directly) and **agent** (minted, never made on the page). A token made before this is a role token and keeps working exactly as it did.

  - 2026-09-30: times you tell a person are in **the user's** local time zone, never UTC in prose (P-367); the zone is on the account and comes back from `GET /api/v2/me` as `tz` (IANA, `null` when unset). What machines read stays ISO 8601 UTC.

  - 2026-09-30: an item's `summary` (P-447): one sentence, at most 200 characters, on `POST /api/v2/pipeline` and `PATCH /api/v2/pipeline/<id>` (`""` clears it); write one on every item you file, or the item's page shows the document's first sentence instead.

  …
• version 13diff 2026-09-30 14:29 UTC ViewText
  What version 14 changed

  …

  Every write sends `Authorization: Bearer <token>`. JSON goes in and out, except topic bodies, which are plain markdown.

   

  +An AI agent also sends `D2-Agent: <its own name>` on every call (`coder-57`: lower-case letters, digits and dashes, starting with a letter, at most 32; anything else is `E_ARG`). That name, and the role its token carries, go on everything it writes — topic and draft versions, objects, pipeline items, the log — so history reads *razie via `coder-57` (coder)* rather than just *razie*. Without the header an agent is known by its token's name, which is fine for one agent per token and wrong as soon as several run in turn. A person, writing as themselves, sends none.

  + 

  **Read lean** (P-345): ask d2 for the rows you want, never for everything and then filter in your own head — reading a whole list when you needed four rows is what fills a chat and ends it early. On the **pipeline**, `?forRole=` (the role and its agent role), `?forName=` and `?status=open` (not done, dropped or moved; or a comma list of statuses) filter on the server, and the list leaves each item's `doc` out: `?fields=id,title,status` narrows a row further, `?fields=all` brings the document back, and `GET /api/v2/pipeline/P-n` reads one item whole. On the **Agents board**, `?since=<the id of the last message you read, or an ISO stamp>` and `?limit=<n>` (the newest n, newest last) give you what is new and nothing more. On a **long topic**, `?section=<id>` reads one section and `PUT …?section=<id>` writes one — send only that section's markdown, its heading line included, and d2 splices it into the rest (the same `If-Match` version check as a whole draft).

   

  …
• version 12diff 2026-09-30 14:08 UTC ViewText
  What version 13 changed

  …

  ## Install

   

  -1. **Network.** Let your AI reach `d2.aiheroapps.com` over HTTPS. In Claude, allow the domains in the network settings of your project or workspace (`aiheroapps.com` and `*.aiheroapps.com` cover them).

  +1. **Network.** Let your AI reach `aiheroapps.com` over HTTPS. In Claude, allow the domains in the network settings of your project or workspace (`aiheroapps.com` and `*.aiheroapps.com` cover them).

  2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **Settings** → **AI permissions** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one.

  **Drafts.** Most tokens write **drafts**: a `PUT` to a topic answers `{"draft": true}` and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their **Drafts** page (`/drafts`, the Drafts button in the top bar), where they see the diff and publish it. `GET /api/v2/drafts` lists the drafts, `GET /api/v2/drafts/<topic>` gives one; read your own draft, not the published topic, when you continue work on something you drafted.

  …
• version 11diff 2026-09-29 19:36 UTC ViewText
  What version 12 changed

  …

  - **Question or instruction:** a message from your person that starts with "q" or ends with "?" is a question: answer it and do nothing else (no changes, items or publishing). Without either, the same words are a go-ahead: do it.

  - **Your status, on every level:** `POST /api/v2/agents/status {agent: "maker", role: "maker", state, text, context, every: 86400}` (`context`: how full your context is, 0–100, your own estimate; on every post): `up` when you start, `working` with what you're building, `waiting` with `waitingOn: ["<their handle>"]` when you need them, `warning` (with `reason`) when something needs their eye, `stopped` when you stop. Their home page shows it (*Your AI: working · the garden planner*).

  +- **Times you tell a person are in the user's local time zone**, e.g. "5:51 PM", with the zone named once when it helps ("Toronto time"); **never UTC in prose**. It is the zone of the **user you report to** — never the box's, never your own host's. API values, commits, log lines, topic frontmatter and anything else a machine reads stay ISO 8601 UTC. Take the zone from `GET /api/v2/me` (`tz`, an IANA name like `America/Toronto`); if it's `null`, ask them once and carry on.

  - **Post notices after the write:** say something is done only after the write it's about has returned.

   

  …

  A project's **pipeline** (`/pipeline`) is its list of work waiting to be done. On a creator project it's just you and your person (roles `user` and `maker agent`); a hero project has none. Each item has an id (`P-12`), a title, a document, who it's for and a status.

   

  -- **Park it:** when your person says "park it", "leave it for later" or "I don't have time now" about an idea, don't act on it and don't lose it: make the item, `POST /api/v2/pipeline {as: "maker", title, prompt: "<their words>", forRole: "maker agent"}`, and park it, `PATCH /api/v2/pipeline/<id> {status: "parked", askedBy: "<their handle>", as: "maker"}`. Give them the item's link (`https://<project>.aiheroapps.com/pipeline/P-12`).

  +- **Park it:** when your person says "park it", "leave it for later" or "I don't have time now" about an idea, don't act on it and don't lose it: make the item, `POST /api/v2/pipeline {as: "maker", title, summary: "<one sentence on what it is, at most 200 characters>", prompt: "<their words>", forRole: "maker agent"}`, and park it, `PATCH /api/v2/pipeline/<id> {status: "parked", askedBy: "<their handle>", as: "maker"}`. Give them the item's link (`https://<project>.aiheroapps.com/pipeline/P-12`).

  - **Coming back to an item:** `POST /api/v2/pipeline/<id>/note {text}` adds to its document; the status stays.

  - **Take your own:** before working on an item for you, `POST /api/v2/pipeline/<id>/take {as: "maker"}` (a `409 E_TAKEN`: someone else has it).

  …

  ## Changelog

   

  +- 2026-09-30: times you tell a person are in **the user's** local time zone, never UTC in prose (P-367); the zone is on the account and comes back from `GET /api/v2/me` as `tz` (IANA, `null` when unset). What machines read stays ISO 8601 UTC.

  +- 2026-09-30: an item's `summary` (P-447): one sentence, at most 200 characters, on `POST /api/v2/pipeline` and `PATCH /api/v2/pipeline/<id>` (`""` clears it); write one on every item you file, or the item's page shows the document's first sentence instead.

  - 2026-09-29: read lean (P-345): the pipeline list leaves `doc` out and takes `fields`, `forRole`, `forName` and `status=open`; the board takes `since` (a message id too) and `limit`; a topic's section is read *and written* by its anchor.

  - 2026-09-29: a project's own process is `Skill:process`, served after the base skills; no copies of base skills (P-302).

  …
• version 10full copy 2026-09-29 19:09 UTC ViewText
  What version 11 changed

  …

  name: d2-maker

  description: Build on a d2 project at <project>.aiheroapps.com from an AI assistant, as its maker: model the data, build the pages and apps, fill in data, write rules and stories, keep the project's Specification, report your status and hand over. Everything any AI needs on d2, fitted to the project's level. Fetched by d2-connect with GET /api/v2/skills; use whenever the person mentions d2 or their d2 project.

  -core: [install, calls, working-with-your-person, log, topics-you-cant-see, new-topics, topics-and-categories, things-to-know]

  +core: [install, calls, working-with-your-person, topics-you-cant-see, new-topics, topics-and-categories, things-to-know]

  ---

   

  …

  **Drafts.** Most tokens write **drafts**: a `PUT` to a topic answers `{"draft": true}` and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their **Drafts** page (`/drafts`, the Drafts button in the top bar), where they see the diff and publish it. `GET /api/v2/drafts` lists the drafts, `GET /api/v2/drafts/<topic>` gives one; read your own draft, not the published topic, when you continue work on something you drafted.

  **Drafts are shared.** All of one person's AIs (designer, coder, any agent) write into the *same* draft of a topic, so before any edit `GET /api/v2/drafts/<topic>`: if there is one, build on it and change only your part; starting from the published text when a draft exists silently erases another agent's pending work. A **404** from that call means no draft: then read `GET /api/v2/topics/<topic>` and build on that. Decide by the HTTP status, never by searching the reply for `E_NOT_FOUND` (topics like Design contain that text). **Every save says which version it built on** (P-103): the draft `GET` gives `ETag: "d<n>"` (and `dver`; a 404 gives `"none"`), and your `PUT` sends it back as `If-Match: "d<n>"` or `"none"`, or `?ver=d<n>` / `?ver=none`. Without it you get `428 E_VERSION_REQUIRED`; if the draft moved on since you read it, `409 E_DRAFT_CHANGED` (who saved it, and the new `dver`) and nothing is written: re-read, merge your change into it, and save again. Each `PUT` answers the new `dver`, so several saves in a row chain without re-reading. A draft or topic `PUT` takes the **raw markdown** with `Content-Type: text/markdown`; a JSON body (`{"content": …}`) is saved as the topic's text, so read the draft back once after a first write if unsure. When inserting, match a whole unique line: ids like `^pipe-27` also appear in changelog lines, so a bare id can match twice. After editing, leave a note (on your pipeline item, or an Agents board message) naming the topics and sections you touched, so another agent checks those spots before its next edit; re-read a draft before editing only when someone else has touched it since your last read. Objects aren't drafts: writes to objects are live. Deleting a topic isn't possible with a drafts token: ask the user.

  -3. **The skills.** Your person installs one small skill once, **d2-connect** (Download d2-connect on the project's Tokens page, `/d2-connect.skill`). At the start of every session it has you fetch the skills for your role and the project's level: `GET /api/v2/skills?role=<your role>` (no role: you are the **maker**), and you follow what comes back, in order. Each skill has a `version`: re-read only when one changes. This skill, `d2-maker`, is the first; on a master project a specialist role also gets `d2-agents`, and a project may add skills of its own. A project's own process lives in `Skill:process`, served after the base skills: read it after them; it narrows the base rules and never loosens a permission. Projects keep no copies of base skills: to change one, propose it on base d2.

  +3. **The skills.** Your person installs one small skill once, **d2-connect** (`/d2-connect.skill`, the Download d2-connect button on the project's **Settings → AI permissions → AI tokens** tab, `/ai/tokens`). At the start of every session it has you fetch the skills for your role and the project's level: `GET /api/v2/skills?role=<your role>` (no role: you are the **maker**), and you follow what comes back, in order. Each skill has a `version`: re-read only when one changes. This skill, `d2-maker`, is the first; on a master project a specialist role also gets `d2-agents`, and a project may add skills of its own. A project's own process lives in `Skill:process`, served after the base skills: read it after them; it narrows the base rules and never loosens a permission. Projects keep no copies of base skills: to change one, propose it on base d2.

  4. **Try it.** Ask your AI to "list the d2 topics" and then "open the Welcome topic".

   

  …

  - People filter the wiki by tag (`/topics?tag=gold`) and search with `#gold` (`GET $B/search?q=%23gold%20nevada`: the tagged topics that also mention nevada, and the tagged files).

   

  -## Memories: what you remember about the user

  +## Memories: what you remember about the user {lookup}

  +when: your person asks you to remember something, or asks what you remember

   

  Keep what you learn about the user in `Memory:` topics instead of only in your own memory, so the user can read and correct it at `/topics?category=Memory`.

  …

  - **Name items as links:** whenever you mention one, link `/pipeline/P-n` with a few words on what it is; people don't remember numbers.

   

  -## All your person's projects: an all-projects token

  +## All your person's projects: an all-projects token {lookup}

  +when: your person wants you to work across several of their projects

   

  A token made with **Scope: All my projects** works on every project your person owns. List them with `GET /api/v2/projects` (on any of them): `{scope, data: [{project, url, level, plan, role}]}`, then call each at its own `url` with the same token. A project token lists only its own project. `401 E_TOKEN_SCOPE` means this token is for another project (the message names it); `403 E_TOKEN_SCOPE` a project your person doesn't own; `403 E_PLAN` that all-projects tokens are paused because your person is on the free plan.

   

  -## Secrets: the vault

  +## Secrets: the vault {lookup}

  +when: you need to store or read a secret (an API key, a password)

   

  Never ask your person to paste a secret (an API key, a GitHub token) into the chat. They keep it in their **vault** (Settings → AI permissions → Vault) and allow your token; you get it with `GET /api/v2/vault/<name>` and your own token (MCP: `vault_get`), at the start of each session. `E_SECRET` means your token isn't allowed it: ask your person to allow it in the vault, naming the secret. Use the value for the task only; never write it into a topic, memory, file, log, commit or chat. At most 30 reads a minute. [[Help:Vault]]

   

  -## Connect over MCP

  +## Connect over MCP {lookup}

  +when: your person wants to connect you over MCP instead of plain HTTP

   

  Every d2 project is also an MCP server, at `https://<project>.aiheroapps.com/mcp` (Streamable HTTP), so an agent that speaks MCP gets d2 as its own tools. In Claude Code:

  …

  - For an app: put its table (or tables) at the top of the app's page, then a line on what it is. Use computed fields for the numbers and the table for the view: don't compute in the page.

   

  -## Live HTML on a page: ```embedhtml

  +## Live HTML on a page: ```embedhtml {lookup}

  +when: a page needs live HTML or a small script in it

   

  When a page needs more than markdown and tables (live numbers from outside, a chart, a small widget), put HTML, CSS and a `<script>` in a ```` ```embedhtml ```` fence. It runs in a sandboxed frame inside the page:

  …

  - Keep it small and show a clear state when a source doesn't answer ("source unreachable"), never a blank. d2portfolio's home has an example: five live market cards.

   

  -## Apps: whole HTML pages

  +## Apps: whole HTML pages {lookup}

  +when: you build a whole-page HTML app

   

  An `App:<name>` topic is a whole HTML page, opened at `/app/<name>` under the project's top bar. Use one when a page needs a free hand (a dashboard, a custom editor); for data on an ordinary page, a ```` ```table ```` is simpler.

  …

  - `layout: full` in the App topic's frontmatter gives it the whole window, with no d2 chrome and a small button home; handle your own navigation (hash links). For now it runs on the project's own address as the viewer, so only make one full-page when the page needs it (a console, an app to put on a phone's home screen).

   

  -## Fetching from the web in rules

  +## Fetching from the web in rules {lookup}

  +when: a rule has to fetch from another site

   

  `http.json(url = …)` and `http.text(url = …)` GET a URL (https, public host names only; 10 s, 2 MB), `csv.parse(text = …)` turns CSV into rows, `json.parse(text = …)` parses JSON. Time spent waiting on them doesn't count against a flow's 5 s, up to 60 s in all. A flow waiting on them pauses; the server keeps serving. They work in rules and flows only; in a computed field, a table or a query they're `E_WAIT`. To fetch many at once: `ids flatMap par (i => http.json(url = …))` (or `map par`), at most 4 at a time by default, `flatMap par 8 (…)` for more (up to 32); results keep their order, and a failure is raised after all branches finish.

  …

  - People manage files on the **Files** page, `/cdn`.

   

  -## Make a stylesheet

  +## Make a stylesheet {lookup}

  +when: your person wants their own look (a stylesheet)

   

  A stylesheet is a `Style:` topic. When the user wants a different look (colours, fonts, the logo text), write one:

  …

  - Then send the user to `https://<project>.aiheroapps.com/styles`, where it's listed under **Style topics** with a **Use this stylesheet** button.

   

  -## Crons: messages on a schedule

  +## Crons: messages on a schedule {lookup}

  +when: something must run on a schedule

   

  A project's rules make crons with `diesel.cron(name, schedule, tz, msg, args)`, best in `Settings:Init` on `diesel.project.on.init` so they're declared on every start (same name replaces). Schedules: 5-field cron, `every 15m`, `hourly`, `daily 03:15` (UTC unless `tz`). Each run is a flow; 5 failures in a row switch it off. See them with `GET /api/v2/crons` or the Crons page; admins `POST /api/v2/crons/<name>/run | on | off`. Details: Help:LifecycleMessages.

  …
• version 9diff 2026-09-29 12:55 UTC ViewText
  What version 10 changed

  …

  Every write sends `Authorization: Bearer <token>`. JSON goes in and out, except topic bodies, which are plain markdown.

   

  +**Read lean** (P-345): ask d2 for the rows you want, never for everything and then filter in your own head — reading a whole list when you needed four rows is what fills a chat and ends it early. On the **pipeline**, `?forRole=` (the role and its agent role), `?forName=` and `?status=open` (not done, dropped or moved; or a comma list of statuses) filter on the server, and the list leaves each item's `doc` out: `?fields=id,title,status` narrows a row further, `?fields=all` brings the document back, and `GET /api/v2/pipeline/P-n` reads one item whole. On the **Agents board**, `?since=<the id of the last message you read, or an ISO stamp>` and `?limit=<n>` (the newest n, newest last) give you what is new and nothing more. On a **long topic**, `?section=<id>` reads one section and `PUT …?section=<id>` writes one — send only that section's markdown, its heading line included, and d2 splices it into the rest (the same `If-Match` version check as a whole draft).

  + 

  ```bash

  B=https://d2pro.aiheroapps.com/api/v2

  …

  curl -s "$B/topics" # list; ?category=Memory or Skill filters

  curl -s "$B/topics/Welcome" # markdown; ?format=json for {name, text, ver, updated}

  +curl -s "$B/topics/Design?section=monitor" # one section (P-345); PUT …?section= writes just that one

  curl -s -X PUT "$B/topics/Frostline" -H "Authorization: Bearer $T" --data-binary @Frostline.md

  curl -s -X DELETE "$B/topics/Memory:old-note" -H "Authorization: Bearer $T"

  …

  ## Changelog

   

  +- 2026-09-29: read lean (P-345): the pipeline list leaves `doc` out and takes `fields`, `forRole`, `forName` and `status=open`; the board takes `since` (a message id too) and `limit`; a topic's section is read *and written* by its anchor.

  - 2026-09-29: a project's own process is `Skill:process`, served after the base skills; no copies of base skills (P-302).

  - 2026-09-29: frontmatter `core:` lists the sections served as d2-core to the specialist roles on master (P-276).

  …
• version 8diff 2026-09-29 10:42 UTC ViewText
  What version 9 changed

  …

  **Drafts.** Most tokens write **drafts**: a `PUT` to a topic answers `{"draft": true}` and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their **Drafts** page (`/drafts`, the Drafts button in the top bar), where they see the diff and publish it. `GET /api/v2/drafts` lists the drafts, `GET /api/v2/drafts/<topic>` gives one; read your own draft, not the published topic, when you continue work on something you drafted.

  **Drafts are shared.** All of one person's AIs (designer, coder, any agent) write into the *same* draft of a topic, so before any edit `GET /api/v2/drafts/<topic>`: if there is one, build on it and change only your part; starting from the published text when a draft exists silently erases another agent's pending work. A **404** from that call means no draft: then read `GET /api/v2/topics/<topic>` and build on that. Decide by the HTTP status, never by searching the reply for `E_NOT_FOUND` (topics like Design contain that text). **Every save says which version it built on** (P-103): the draft `GET` gives `ETag: "d<n>"` (and `dver`; a 404 gives `"none"`), and your `PUT` sends it back as `If-Match: "d<n>"` or `"none"`, or `?ver=d<n>` / `?ver=none`. Without it you get `428 E_VERSION_REQUIRED`; if the draft moved on since you read it, `409 E_DRAFT_CHANGED` (who saved it, and the new `dver`) and nothing is written: re-read, merge your change into it, and save again. Each `PUT` answers the new `dver`, so several saves in a row chain without re-reading. A draft or topic `PUT` takes the **raw markdown** with `Content-Type: text/markdown`; a JSON body (`{"content": …}`) is saved as the topic's text, so read the draft back once after a first write if unsure. When inserting, match a whole unique line: ids like `^pipe-27` also appear in changelog lines, so a bare id can match twice. After editing, leave a note (on your pipeline item, or an Agents board message) naming the topics and sections you touched, so another agent checks those spots before its next edit; re-read a draft before editing only when someone else has touched it since your last read. Objects aren't drafts: writes to objects are live. Deleting a topic isn't possible with a drafts token: ask the user.

  -3. **The skills.** Your person installs one small skill once, **d2-connect** (Download d2-connect on the project's Tokens page, `/d2-connect.skill`). At the start of every session it has you fetch the skills for your role and the project's level: `GET /api/v2/skills?role=<your role>` (no role: you are the **maker**), and you follow what comes back, in order. Each skill has a `version`: re-read only when one changes. This skill, `d2-maker`, is the first; on a master project a specialist role also gets `d2-agents`, and a project may add skills of its own.

  +3. **The skills.** Your person installs one small skill once, **d2-connect** (Download d2-connect on the project's Tokens page, `/d2-connect.skill`). At the start of every session it has you fetch the skills for your role and the project's level: `GET /api/v2/skills?role=<your role>` (no role: you are the **maker**), and you follow what comes back, in order. Each skill has a `version`: re-read only when one changes. This skill, `d2-maker`, is the first; on a master project a specialist role also gets `d2-agents`, and a project may add skills of its own. A project's own process lives in `Skill:process`, served after the base skills: read it after them; it narrows the base rules and never loosens a permission. Projects keep no copies of base skills: to change one, propose it on base d2.

  4. **Try it.** Ask your AI to "list the d2 topics" and then "open the Welcome topic".

   

  …

  ## Changelog

   

  +- 2026-09-29: a project's own process is `Skill:process`, served after the base skills; no copies of base skills (P-302).

  - 2026-09-29: frontmatter `core:` lists the sections served as d2-core to the specialist roles on master (P-276).

  - 2026-09-29: the user makes tokens and keeps secrets under Settings → AI permissions (`/ai`, P-271).

  …
• version 7diff 2026-09-29 10:17 UTC ViewText
  What version 8 changed

  …

  name: d2-maker

  description: Build on a d2 project at <project>.aiheroapps.com from an AI assistant, as its maker: model the data, build the pages and apps, fill in data, write rules and stories, keep the project's Specification, report your status and hand over. Everything any AI needs on d2, fitted to the project's level. Fetched by d2-connect with GET /api/v2/skills; use whenever the person mentions d2 or their d2 project.

  +core: [install, calls, working-with-your-person, log, topics-you-cant-see, new-topics, topics-and-categories, things-to-know]

  ---

   

  …

  ## Changelog

   

  +- 2026-09-29: frontmatter `core:` lists the sections served as d2-core to the specialist roles on master (P-276).

  - 2026-09-29: the user makes tokens and keeps secrets under Settings → AI permissions (`/ai`, P-271).

  - 2026-09-29: many objects: use `/api/v2/dom/batch` (P-257).

  …
• version 6diff 2026-09-29 02:15 UTC ViewText
  What version 7 changed

  …

   

  1. **Network.** Let your AI reach `d2.aiheroapps.com` over HTTPS. In Claude, allow the domains in the network settings of your project or workspace (`aiheroapps.com` and `*.aiheroapps.com` cover them).

  -2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **AI tokens** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one.

  +2. **Token.** Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → **Settings** → **AI permissions** → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with `d2t_`, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one.

  **Drafts.** Most tokens write **drafts**: a `PUT` to a topic answers `{"draft": true}` and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their **Drafts** page (`/drafts`, the Drafts button in the top bar), where they see the diff and publish it. `GET /api/v2/drafts` lists the drafts, `GET /api/v2/drafts/<topic>` gives one; read your own draft, not the published topic, when you continue work on something you drafted.

  **Drafts are shared.** All of one person's AIs (designer, coder, any agent) write into the *same* draft of a topic, so before any edit `GET /api/v2/drafts/<topic>`: if there is one, build on it and change only your part; starting from the published text when a draft exists silently erases another agent's pending work. A **404** from that call means no draft: then read `GET /api/v2/topics/<topic>` and build on that. Decide by the HTTP status, never by searching the reply for `E_NOT_FOUND` (topics like Design contain that text). **Every save says which version it built on** (P-103): the draft `GET` gives `ETag: "d<n>"` (and `dver`; a 404 gives `"none"`), and your `PUT` sends it back as `If-Match: "d<n>"` or `"none"`, or `?ver=d<n>` / `?ver=none`. Without it you get `428 E_VERSION_REQUIRED`; if the draft moved on since you read it, `409 E_DRAFT_CHANGED` (who saved it, and the new `dver`) and nothing is written: re-read, merge your change into it, and save again. Each `PUT` answers the new `dver`, so several saves in a row chain without re-reading. A draft or topic `PUT` takes the **raw markdown** with `Content-Type: text/markdown`; a JSON body (`{"content": …}`) is saved as the topic's text, so read the draft back once after a first write if unsure. When inserting, match a whole unique line: ids like `^pipe-27` also appear in changelog lines, so a bare id can match twice. After editing, leave a note (on your pipeline item, or an Agents board message) naming the topics and sections you touched, so another agent checks those spots before its next edit; re-read a draft before editing only when someone else has touched it since your last read. Objects aren't drafts: writes to objects are live. Deleting a topic isn't possible with a drafts token: ask the user.

  …

  ## Secrets: the vault

   

  -Never ask your person to paste a secret (an API key, a GitHub token) into the chat. They keep it in their **vault** (AI tokens → Vault) and allow your token; you get it with `GET /api/v2/vault/<name>` and your own token (MCP: `vault_get`), at the start of each session. `E_SECRET` means your token isn't allowed it: ask your person to allow it in the vault, naming the secret. Use the value for the task only; never write it into a topic, memory, file, log, commit or chat. At most 30 reads a minute. [[Help:Vault]]

  +Never ask your person to paste a secret (an API key, a GitHub token) into the chat. They keep it in their **vault** (Settings → AI permissions → Vault) and allow your token; you get it with `GET /api/v2/vault/<name>` and your own token (MCP: `vault_get`), at the start of each session. `E_SECRET` means your token isn't allowed it: ask your person to allow it in the vault, naming the secret. Use the value for the task only; never write it into a topic, memory, file, log, commit or chat. At most 30 reads a minute. [[Help:Vault]]

   

  ## Connect over MCP

  …

  ## Changelog

   

  +- 2026-09-29: the user makes tokens and keeps secrets under Settings → AI permissions (`/ai`, P-271).

  - 2026-09-29: many objects: use `/api/v2/dom/batch` (P-257).

  - 2026-09-29: tables are drawn with the page (reload for new data); the class `?stamp=1` is gone (P-236).

  …
• version 5diff 2026-09-29 00:35 UTC ViewText
  What version 6 changed

  …

  curl -s -X PUT "$B/dom/val/Company:FLR" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @flr.json

  curl -s -X POST "$B/dom/val/Company" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @new.json # 409 if the key exists

  +curl -s -X POST "$B/dom/batch" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @many.json # many objects: see below

   

  # files and images (see "Files" below): upload here, serve from cdn.aidieselapps.com

  …

  - Declare a relationship on one side only; the inverse is inferred. After saving, check `domain/overview` for `errors` and `warnings`.

  - Objects can be declared in a Story (or Spec) topic with `$object Class:key (field = value, …)`, or written through the API. Writes are checked against the class, and a failed write returns `E_VALIDATION` with a `problems` list naming each bad field.

  +- **Many objects: use `/api/v2/dom/batch`**, one request instead of one per object: `POST {mode, writes: [{op: "put" | "create" | "delete", cls, key, data}]}`, across classes; `put` replaces the whole object (read, change, put it back). Every write is checked first; `mode: "all"` (the default) writes nothing if one is bad (422 `E_VALIDATION`, the bad writes listed with their problems), `"each"` writes the good ones and lists the bad. The answer is `{ok, written, results: [{i, cls, key, result: created | replaced | deleted | failed, problems?}]}`. Up to 200 writes and 2 MB a batch (`E_QUOTA`); it costs one write per 50 objects of your per-minute limit.

  - **Computed fields:** `@calc(expr) name: Type` works a field out from the others each time the object is read: `@calc(shares * avgCost) cost: Number`, `@calc(shares * company.price) value: Number` (through a reference), `@calc(if cost > 0 then pl / cost * 100 else 0) plPct: Number`. One expression, no loops; it's never stored and never written (a write that includes it just drops it). A formula that fails (a missing reference, a division by zero) gives `null`. Use them for anything the user would otherwise compute by hand: totals per row, P/L, days since, a status from a date.

  - `query` takes an expression over an object's fields: `stage is "Producer" and marketCap > 100000000`, or `"prop-frost" in (properties ?? [])` for a reference list.

  …

  ## Changelog

   

  +- 2026-09-29: many objects: use `/api/v2/dom/batch` (P-257).

  - 2026-09-29: tables are drawn with the page (reload for new data); the class `?stamp=1` is gone (P-236).

  - 2026-09-28: tables redraw by themselves when their data changes; `?stamp=1` on a class (P-201).

  …
• version 4diff 2026-09-28 21:32 UTC ViewText
  What version 5 changed

  …

  ## Tables: show data on any page

   

  -A ```` ```table ```` fence puts a live table of a class's objects in any topic: a home page, a notes page, a report. Use it whenever the user wants to *see* their data; it's the usual way to give an app its page. One `key: value` per line:

  +A ```` ```table ```` fence puts a table of a class's objects in any topic, drawn with the page (reload for new data),: a home page, a notes page, a report. Use it whenever the user wants to *see* their data; it's the usual way to give an app its page. One `key: value` per line:

   

  ````

  …

  - `totals` adds a sum row under those columns (a total for a field that isn't a column shows as a line under the table). `sort` is a column, `asc` or `desc`. `filter` is an expression, as in `query` (`account is "TFSA"`). `color` makes numbers green above zero and red below. `add: no` hides the **+ Add** button; `title` and `limit` do what they say.

  - The first cell of each row opens the object's edit form and **+ Add** the new-object form; both come back to the page after saving. On a phone each row becomes a card.

  -- An open page redraws its tables by itself when their objects change (or those they reference): no reload needed after you write data. `GET /api/v2/dom/val/<Class>?stamp=1` gives the stamp it follows.

  +- A table is drawn with the page and shows the data as of that load; it doesn't update itself while the page is open (reload for new data).

  - A mistake (a class or field that doesn't exist) shows as a red note in place of the table: read the page after saving it and fix what it says.

  - For an app: put its table (or tables) at the top of the app's page, then a line on what it is. Use computed fields for the numbers and the table for the view: don't compute in the page.

  …

  ## Changelog

   

  +- 2026-09-29: tables are drawn with the page (reload for new data); the class `?stamp=1` is gone (P-236).

  - 2026-09-28: tables redraw by themselves when their data changes; `?stamp=1` on a class (P-201).

  - 2026-09-28: permissions: *person* is your person themself only; *asks* runs at once with askedBy (P-176).

  …
• version 3diff 2026-09-28 20:17 UTC ViewText
  What version 4 changed

  …

  - `totals` adds a sum row under those columns (a total for a field that isn't a column shows as a line under the table). `sort` is a column, `asc` or `desc`. `filter` is an expression, as in `query` (`account is "TFSA"`). `color` makes numbers green above zero and red below. `add: no` hides the **+ Add** button; `title` and `limit` do what they say.

  - The first cell of each row opens the object's edit form and **+ Add** the new-object form; both come back to the page after saving. On a phone each row becomes a card.

  +- An open page redraws its tables by itself when their objects change (or those they reference): no reload needed after you write data. `GET /api/v2/dom/val/<Class>?stamp=1` gives the stamp it follows.

  - A mistake (a class or field that doesn't exist) shows as a red note in place of the table: read the page after saving it and fix what it says.

  - For an app: put its table (or tables) at the top of the app's page, then a line on what it is. Use computed fields for the numbers and the table for the view: don't compute in the page.

  …

  ## Changelog

   

  +- 2026-09-28: tables redraw by themselves when their data changes; `?stamp=1` on a class (P-201).

  - 2026-09-28: permissions: *person* is your person themself only; *asks* runs at once with askedBy (P-176).

  - 2026-09-28: split out of `Skill:diesel2` (P-146): what every AI needs to build on d2; the level line; the pipeline lightly (park, take your own, close); the role work moved to `d2-agents`. Served by `GET /api/v2/skills`.

  …
• version 2diff 2026-09-28 19:41 UTC ViewText
  What version 3 changed

  …

  - **Close it** when it's done: `PATCH /api/v2/pipeline/<id> {status: "done", as: "maker"}`, with a note of what changed; if it goes to `review`, your person accepts it. `waiting-input` with `waitingOn: <their handle>` when you need their answer.

  - **Your person's calls:** moving an item, marking it important, ranking or dropping it happen only when they tell you to, with `askedBy: "<their handle>"`; when you only think it should happen, say so in the chat.

  -- **Permissions:** `GET /api/v2/permissions` gives each action's mode: *person* (403 `E_SCOPE`: ask them), *asks* (202 `{approval: "P-n"}`: it runs once they approve; don't retry), *tells*, *free*. See Help:Permissions.

  +- **Permissions:** `GET /api/v2/permissions` gives each action's mode: *person* (only they do it, themself: 403 `E_SCOPE` even when they told you; ask them), *asks* (when they told you to, send `askedBy: "<their handle>"` and it runs at once; without it 202 `{approval: "P-n"}`: it runs once they approve; don't retry), *tells*, *free*. See Help:Permissions.

  - **Name items as links:** whenever you mention one, link `/pipeline/P-n` with a few words on what it is; people don't remember numbers.

   

  …

  ## Changelog

   

  +- 2026-09-28: permissions: *person* is your person themself only; *asks* runs at once with askedBy (P-176).

  - 2026-09-28: split out of `Skill:diesel2` (P-146): what every AI needs to build on d2; the level line; the pipeline lightly (park, take your own, close); the role work moved to `d2-agents`. Served by `GET /api/v2/skills`.

   
• version 1diff 2026-09-28 18:28 UTC ViewText
  What version 2 changed

  …

   

  - **Question or instruction:** a message from your person that starts with "q" or ends with "?" is a question: answer it and do nothing else (no changes, items or publishing). Without either, the same words are a go-ahead: do it.

  -- **Your status, on every level:** `POST /api/v2/agents/status {agent: "maker", role: "maker", state, text, every: 86400}`: `up` when you start, `working` with what you're building, `waiting` with `waitingOn: ["<their handle>"]` when you need them, `warning` (with `reason`) when something needs their eye, `stopped` when you stop. Their home page shows it (*Your AI: working · the garden planner*).

  +- **Your status, on every level:** `POST /api/v2/agents/status {agent: "maker", role: "maker", state, text, context, every: 86400}` (`context`: how full your context is, 0–100, your own estimate; on every post): `up` when you start, `working` with what you're building, `waiting` with `waitingOn: ["<their handle>"]` when you need them, `warning` (with `reason`) when something needs their eye, `stopped` when you stop. Their home page shows it (*Your AI: working · the garden planner*).

  - **Post notices after the write:** say something is done only after the write it's about has returned.

   

  …

  - **A story per feature:** a `Story:` topic with the same `feature: <id>`, run after a change; its last run makes the row *checked* (or *fails*, with a **Fix it** for you).

  - A part or story naming an id the Specification doesn't have shows under *Not described yet*: add the line. On pro the same `Spec` is the project's specification, so nothing is lost when it moves up.

  -- **Your status, on every level:** post it like any agent, as the maker: `POST /api/v2/agents/status {agent: "maker", role: "maker", state, text}` (`working` with what you're building, `waiting`, `handing-over`…). The person's home page shows it (*Your AI: working · the garden planner*). Below master that's the only board call you have (and `GET /api/v2/agents/history`).

  +- **Your status, on every level:** post it like any agent, as the maker: `POST /api/v2/agents/status {agent: "maker", role: "maker", state, text, context}` (`context`: how full your context is, 0–100, on every post; `working` with what you're building, `waiting`, `handing-over`…). The person's home page shows it (*Your AI: working · the garden planner*). Below master that's the only board call you have (and `GET /api/v2/agents/history`).

  - **Handing over** when your chat is full: on **creator**, post `handing-over`, make a handover item (`POST /api/v2/pipeline {as: "maker", kind: "handover", forRole: "maker agent", title, prompt}`: where things are, what's next, and the start prompt *You are the maker on <project>. Carry on.*), then tell your person; no separate start-a-new-chat item. On **hero** (no pipeline) write it as the **first line of the Log**, starting *where I left off:* (what you were doing, what's next). **Starting a new chat:** take the handover (creator) or read the Log's first line (hero) before anything else.

   

  …

  A project's **pipeline** (`/pipeline`) is its list of work waiting to be done. On a creator project it's just you and your person (roles `user` and `maker agent`); a hero project has none. Each item has an id (`P-12`), a title, a document, who it's for and a status.

   

  -- **Park it:** when your person says "park it", "leave it for later" or "I don't have time now" about an idea, don't act on it and don't lose it: `POST /api/v2/pipeline {as: "maker", title, prompt: "<their words>", forRole: "maker agent"}`. Give them the item's link (`https://<project>.aiheroapps.com/pipeline/P-12`).

  +- **Park it:** when your person says "park it", "leave it for later" or "I don't have time now" about an idea, don't act on it and don't lose it: make the item, `POST /api/v2/pipeline {as: "maker", title, prompt: "<their words>", forRole: "maker agent"}`, and park it, `PATCH /api/v2/pipeline/<id> {status: "parked", askedBy: "<their handle>", as: "maker"}`. Give them the item's link (`https://<project>.aiheroapps.com/pipeline/P-12`).

  - **Coming back to an item:** `POST /api/v2/pipeline/<id>/note {text}` adds to its document; the status stays.

  - **Take your own:** before working on an item for you, `POST /api/v2/pipeline/<id>/take {as: "maker"}` (a `409 E_TAKEN`: someone else has it).

  …