Schema

CREATE TABLE roles (
	name            TEXT PRIMARY KEY,
	title           TEXT NOT NULL DEFAULT '',
	soul            TEXT NOT NULL DEFAULT '',
	tools           TEXT NOT NULL DEFAULT '[]',   -- JSON array of MCP tool names
	builtin         INTEGER NOT NULL DEFAULT 0,
	can_grant_roles INTEGER NOT NULL DEFAULT 0,
	created_by      TEXT NOT NULL DEFAULT '',
	created_at      TEXT NOT NULL,
	updated_at      TEXT NOT NULL
);

Semantics

• tools is the authority. It is read by both tools/list (visibility) and tools/call (enforcement); there is no second source of truth.
• soul is advisory. It becomes the bot's SOUL.md, shaping voice and intent. A prompt can argue with a soul; it cannot argue with a missing tool.
• builtin rows are seeded once with INSERT OR IGNORE, so an operator edit is preserved. They cannot be deleted.
• can_grant_roles is what makes a role able to define other roles. Only the seeded master has it, and it is the check roles.create performs — not a name comparison.

Invariants

• A role in use cannot be deleted (users.role would point at nothing).
• An unknown role resolves to no tools rather than to a default set.
• users.role is validated against this table on create and on update, so custom roles work from the CLI and the UI, not only from MCP.

Rendered from nx-master/data-model/roles.md · OKF bundle · regenerate with npm run render