Starting a session
Every session must begin withmaxi/bootstrap-session. This is server-enforced — all other abilities are blocked until the bootstrap call is acknowledged.
Bootstrap returns four things:
1
Operational playbook
The behavioral rules, content guards, and workflows the agent must follow on this site. This is the authoritative reference for how the agent should operate.
2
Active operator notes
Live instructions from the site operator. These are authoritative — the agent reads and obeys them directly. Operator notes take precedence over any default behavior.
3
Knowledge note headers
A list of
agent-knowledge notes with id, title, topic, and priority. Agents scan these titles before starting a task. If a title matches the task, the agent fetches the full note with maxi/get-note and applies the documented solution — avoiding re-solving problems that are already figured out.4
Available reference docs
On-demand playbooks that can be fetched with
maxi/get-playbook when the task requires deeper reference material.Session identity
How a session is identified depends on your authentication method.Ability acknowledgements
When an agent acknowledges an ability rule (by reading and retrying through areject_first gate, or by receiving a rule on an inline_on_success call), that acknowledgement is stored for the session. The rule is not re-delivered on subsequent calls to the same ability in the same session.
If an operator updates a rule’s content mid-session, its version bumps. The next call to that ability re-delivers _meta._rule — treat this as “the rule just changed, re-read it.”
Live refresh for operator notes
After bootstrap, every ability response includes_meta.operator_notes_revision. The agent records the value from bootstrap as its baseline. If a later response carries a higher revision number, the agent refreshes operator notes before the next tool call:
maxi/list-notes with type=operator-note and status=active, apply the returned instructions going forward, and update the baseline. The in-flight request is not blocked — this is a soft signal, not a gate.
Live refresh for knowledge notes
The same pattern applies to knowledge notes via_meta.knowledge_notes_revision. When the revision increases, call maxi/list-notes with type=agent-knowledge and status=active to refresh knowledge note headers. Use the refreshed headers the same way you used bootstrap’s: scan titles against the current task and fetch the full note if one matches.
Both live-refresh signals are soft — the current in-flight request continues normally. The refresh happens before the next call, not the current one.