Agent Identity And Docs (SOUL.md, USER.md, TOOLS.md)

Rooaak uses three primary "docs" files to shape runtime behavior:

• SOUL.md: system-level identity and non-negotiable rules for the agent.
• TOOLS.md: tool availability and usage rules (what the agent can do, how to call tools safely).
• USER.md: user-specific or dynamic context (what changes per customer, conversation, or session).

Docs are versioned and delivered to the runtime as part of config rollout.

Recommended setup (fast path)

1. Publish project doc versions for soul, tools, and user.
2. Set project defaults to those versions (so new agents inherit them).
3. Override per-agent only when needed (exceptions, experiments).

Project docs

Project docs endpoints:

• GET /v1/projects/:id/docs
• POST /v1/projects/:id/docs/:docType/versions
• PUT /v1/projects/:id/docs/defaults

docType is one of: soul, tools, user.

Agent overrides

Agent doc overrides endpoint:

• PUT /v1/agents/:id/docs

This pins a specific version (or null to inherit) per doc type.

When docs change, Rooaak bumps the agent config version and the runtime applies the new docs via config rollout.

USER.md and dynamic updates

USER.md is the right place for frequently changing context:

• a customer's plan/tier
• preferences
• business rules that vary per user

If you provide a contextUrl on the agent, Rooaak can fetch additional dynamic context at runtime and merge it into USER.md using reserved markers.

Operational tips

• Keep SOUL.md stable: change it rarely and treat it like a "contract".
• Put changeable behavior in TOOLS.md and USER.md.
• After updating docs, call POST /v1/agents/:id/reload (hot apply) unless you need a hard reset (restart).