Skip to main content
Subdirectory: operational_rules/ · Body: the rule text The MDX body is the rule itself — the directive the agent reads when this rule matches a task. See Prompting an Operational Rule for what makes a good rule body.

​
Frontmatter

FieldTypeRequiredDefaultDescription
orgstring | nullNotenantOrganization name. Omit (or null) to make the rule available to every org in the tenant.
namestringYes—Display name. Used in the matching trace on each task.
tagsstring[]No[]Vocab-validated tags that scope this rule.

​
Fields NOT supported

  • id, tenant_id, created_at, updated_at — system-set
  • The rule text — lives in the body, not frontmatter
  • document_id, source_section, text_hash — these mark rules auto-extracted from Knowledge uploads; declaring them in MDX would collide with the extractor

​
Example

operational_rules/nginx-restart.mdx
---
org: platform-team
name: nginx-restart
tags:
  - os:linux
  - tech:nginx
  - procedure:restart
---
To restart nginx, run `sudo systemctl reload nginx` first; only fall back to
`restart` if reload fails. After acting, verify with `systemctl status nginx`
and confirm the service is `active (running)` before reporting the task done.

Why: a restart drops in-flight connections. Reload is graceful.

​
Tag scoping rules

Rules are matched against the target host’s tags and against tags inferred from the task action. The rule applies only when every one of its tags satisfies one of those sources.
  • A rule with no tags applies broadly — anywhere in the org.
  • Adding scope tags (os:, type:, tech:, shell:, app:*) narrows it to fewer hosts.
  • Adding a procedure tag (procedure:restart, procedure:deploy, etc.) narrows it to fewer actions.
  • A rule with multiple procedure tags matches if any of them matches.
See Operational Rules for the full vocabulary and the matching trace.

​
Gotchas

  • Untagged + tenant-scoped = applied to everything. A rule with no org and no tags becomes a universal guardrail. Use sparingly.
  • tags is the only scope mechanism. No host:<name> pin exists — rule retrieval is pure tag intersection. To target a specific host, give it (and the rule) a matching app:<name> tag.
  • Auto-extracted rules from Knowledge can be replaced by re-uploads. A rule you declare in MDX is independent of the extractor and won’t be touched by re-ingest.