tags: help, lifecycle
---
-# Help: lifecycle messages
+# Help: the messages your rules can handle
-d2 sends these messages in your project as things happen, so your rules can react. Handle them in the project's init page, `Settings:Init` (**Admin → Init**); [[Help:InitExample]] shows one at work.
+d2 raises these **events** in your project as things happen, so your rules can react. Every event's name has `.on.` after its area and says what happened, like `diesel.entity.on.created`. Handle them in the project's init page, `Settings:Init` (**Admin → Init**); [[Help:InitExample]] shows one at work.
-Each is sent only when your project has a rule for it. It runs as a flow that can write objects, after whatever caused it, and you can open it under **Flows**. A mistake in a rule shows there and in the audit log, and never stops the project.
+Each runs only when your project has a rule for it. It runs as a flow that can write objects, after whatever caused it, and you can open it under **Flows**. A mistake in a rule shows there and in the audit log, and never stops the project. Your rules only ever see your own project's events, and they can't send an event themselves (that's `E_NATIVE`): only d2 raises them.
## The project
+
+- **`diesel.project.on.init (project)`**: the project was loaded (d2 started, or was updated), or its init page was saved. The place to set up what the project needs, since it runs again whenever you change the page.
+- **`diesel.project.on.created (project, owner)`**: once, when the project was made.
+- **`diesel.project.on.released (project, version)`**: after a release (**Admin → Project**); `version` is the new one, like `1.2.0`.
+## People
+
+- **`diesel.project.on.joinRequested (project, email)`**: someone asked to join.
+- **`diesel.project.on.joinApproved (project, email, by)`** and **`diesel.project.on.joinDeclined (project, email, by)`**: an admin answered.
-- **`diesel.project.init (project)`**: the project was loaded (d2 started, or was updated), or its init page was saved. The place to set up what the project needs, since it runs again whenever you change the page.
-- **`diesel.project.created (project)`**: once, when the project was made.
+- **`diesel.project.on.invited (project, email, role, by, link)`**: someone was invited; **`diesel.project.on.inviteAccepted (project, email, role, by)`** and **`diesel.project.on.inviteDeclined (project, email, by)`**: they answered.
+- **`diesel.project.on.roleChanged (project, email, role, by)`**: a member's role changed.
-- **`diesel.project.released (project, version)`**: after a release (**Admin → Project**); `version` is the new one, like `1.2.0`.
## Objects
+- **`diesel.entity.on.created (realm, category, key)`**: an object was added, by a form, the API, your AI or a flow.
+- **`diesel.entity.on.updated (realm, category, key)`**: an object was changed.
-- **`diesel.entity.created (realm, category, key)`**: an object was added, by a form, the API, your AI or a flow.
-- **`diesel.entity.updated (realm, category, key)`**: an object was changed.
-- **`diesel.entity.deleted (realm, category, key)`**: an object was deleted.
+- **`diesel.entity.on.deleted (realm, category, key)`**: an object was deleted.
+`category` is the object's class and `key` its key; pick the ones a rule is for with a condition, like `$when diesel.entity.on.created (category, key) if (category is "Holding") { … }`. Not sent for a scratch run (the fiddle, or a run that doesn't write), nor for the sample objects a spec declares. The writes a rule makes while handling one of these don't send more of them, so a rule can't loop.
-`category` is the object's class and `key` its key; pick the ones a rule is for with a condition, like `$when diesel.entity.created (category, key) if (category is "Holding") { … }`. Not sent for a scratch run (the fiddle, or a run that doesn't write), nor for the sample objects a spec declares. The writes a rule makes while handling one of these don't send more of them, so a rule can't loop.
+## Pages
+
+Each with `(project, topic, category, ver, by)`:
+
+- **`diesel.topic.on.created (…)`**, **`diesel.topic.on.saved (…)`** (a new version), **`diesel.topic.on.published (…)`** (a draft was published), **`diesel.topic.on.deleted (…)`** (to the trash), **`diesel.topic.on.restored (…, from)`** (from the trash or an older version).
+- **`diesel.draft.on.saved (…)`**, **`diesel.draft.on.conflict (…, with)`** (someone else has a draft of the same page), **`diesel.draft.on.discarded (…)`**.
+
+For example, `$when diesel.topic.on.published (topic, category) if (category is "Recipe") { … }`.
+
+## Limits
+
+- **`diesel.quota.on.reached (project, quota, limit, message)`**: the project reached one of its plan's limits; the write was refused.
+
+## The pipeline and your AI agents
+
+Each pipeline event carries `(id, title, kind, forRole, forName, by)`:
+
+- **`diesel.ai.pipeline.on.created (…)`**, **`diesel.ai.pipeline.on.assigned (…)`**, **`diesel.ai.pipeline.on.waitingInput (…)`**, **`diesel.ai.pipeline.on.taken (…)`**, **`diesel.ai.pipeline.on.handedOn (…)`**, **`diesel.ai.pipeline.on.statusChanged (…)`**, **`diesel.ai.pipeline.on.done (…)`**, **`diesel.ai.pipeline.on.dropped (…)`**, **`diesel.ai.pipeline.on.unlocked (…)`**, **`diesel.ai.pipeline.on.followup (…)`**.
+
+And the agents' board:
+
+- **`diesel.ai.board.on.status (handle, agent, role, state, text, item)`**, **`diesel.ai.board.on.message (handle, from, to, text, item)`**, **`diesel.ai.board.on.stuck (handle, agent, role, text)`**, **`diesel.ai.board.on.gone (handle, agent, role, state, text)`**.
+- **`diesel.token.on.limited (token, email, kind)`**: an AI token keeps going over its rate limits.
+
## Coming later
-- `diesel.user.joined`, `diesel.user.left (email, role)`: someone joined or left the project.
+Requests your rules can send (a notice to a member, managing pipeline items, a message to your agents), crons and email.
-- `diesel.quota.reached (quota)`: the project reached one of its plan's limits.