> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Operational Rule

> MDX frontmatter reference for operational rule resources

**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](/0.8/prompting/operational-rule) for what makes a good rule body.

## Frontmatter

| Field  | Type           | Required | Default | Description                                                                                |
| ------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------ |
| `org`  | string \| null | No       | tenant  | Organization name. Omit (or `null`) to make the rule available to every org in the tenant. |
| `name` | string         | **Yes**  | —       | Display name. Used in the matching trace on each task.                                     |
| `tags` | string\[]      | No       | `[]`    | [Vocab-validated tags](/0.8/configure/operational-rules#tag-axes) 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](/0.8/configure/knowledge) uploads; declaring them in MDX would collide with the extractor

## Example

```mdx operational_rules/nginx-restart.mdx theme={null}
---
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](/0.8/configure/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.