Rules that reach your agents

A rule (an instruction, in the API) is a piece of standing guidance for whoever works on this product - a person or an agent. Not a task and not a document: a task gets done and stops existing, a document is read when somebody goes looking, and a rule is meant to be in the room already.

A service named redis collides with coolify-redis on the shared network. Name it <product>-redis.

That is worth everything at the moment somebody writes a compose file and worth nothing when found afterwards by searching the error text. Getting it to arrive at the first moment rather than the second is what the whole feature is about.

A new rule reaches nobody

Writing a rule down and putting it in force are two separate acts. A rule you create is a draft: it is not in any set, not in any context package, and preflight_operation will not return it. Publish it on its own page when it says what you meant.

This is not ceremony. Before it existed, saving a half-finished sentence put that sentence into every agent's system prompt immediately, and editing a live rule meant agents read the intermediate wording. It also means the honest answer to "I wrote a rule and nothing happened" is usually "it is still a draft" - the rule's page says so in a sentence, not a badge.

Your own list shows drafts and marks them. Only delivery hides them.

How a published rule actually arrives

Three paths, and they fire at different moments:

1. Through a set, into the system prompt. Rules are grouped into named sets; a setup profile pins a set at a version, and apply_setup_profile hands the package to your client, which writes it to the machine. This is the "always in the room" path.
2. With the product. get_product_context carries the applicable rules alongside the board, the open decisions and the knowledge - so an agent opening a product has them without asking.
3. At the moment of an operation. preflight_operation takes an intent ("write_compose", "rotate_credential") and returns the rules whose triggers match it. makermap cannot interrupt an agent - it is a server your client pulls from - so the delivery point is a question the agent was already asking.

The four fields that make a rule findable

Beyond a title and a body, a rule can carry:

• severity - info, warning or blocker. How much it matters when it applies.
• symptom - what hitting it looks like, e.g. "NOAUTH Authentication required". A rule you can recognise beats one you can only read.
• antiPattern - what does not fix it, and why it looks like it did. Usually the most valuable field on the whole record: a false fix looks successful, and re-pasting a key through the UI can appear to work and break again on the next deploy.
• triggers - the operation intents that should surface it in preflight_operation.

All four are optional. A rule with none of them behaves exactly as it always did.

Editing, history and retiring

Every edit copies the previous state into a revision, so nothing is overwritten and you can read any past version. Retiring a rule archives it - the text and the whole history survive, sets stop delivering it, and a setup profile that pinned an older version still resolves. Withdrawing a published rule back to a draft is the softer move: it stops reaching agents without archiving anything.

Over MCP

list_instructions and get_instructions read; save_instructions writes a batch, and saves drafts unless you pass published: true - the answer tells you which you did. update_instruction publishes or withdraws one. Sets have their own verbs (list_instruction_sets, create_instruction_set, snapshot_instruction_set). All of it needs instructions:read or instructions:write.