docs: add docs for boundary rules engine (#21471)

Closes: https://github.com/coder/boundary/issues/146

- added docs for rules engine
- move all boundary-related docs under new `boundary` directory

docs/ai-coder/boundary/agent-boundary.md

@@ -2,7 +2,7 @@
 
 Agent Boundaries are process-level firewalls that restrict and audit what autonomous programs, such as AI agents, can access and use.
 
-![Screenshot of Agent Boundaries blocking a process](../images/guides/ai-agents/boundary.png)Example of Agent Boundaries blocking a process.
+![Screenshot of Agent Boundaries blocking a process](../../images/guides/ai-agents/boundary.png)Example of Agent Boundaries blocking a process.
 
 ## Supported Agents
 
@@ -78,6 +78,8 @@ Boundary automatically reads `config.yaml` from `~/.config/coder_boundary/` when
   - `method=POST domain=api.example.com path=/users,/posts` - allows specific methods, domain, and paths
   - `path=/api/v1/*,/api/v2/*` - allows specific URL paths
 
+For detailed information about the rules engine and how to construct allowlist rules, see the [rules engine documentation](./rules-engine.md).
+
 You can also run Agent Boundaries directly in your workspace and configure it per template. You can do so by installing the [binary](https://github.com/coder/boundary) into the workspace image or at start-up. You can do so with the following command:
 
 ```hcl

docs/ai-coder/boundary/rules-engine.md

@@ -0,0 +1,98 @@
+# Rules Engine Documentation
+
+## Overview
+
+The `rulesengine` package provides a flexible rule-based filtering system for HTTP/HTTPS requests. Rules use a simple key-value syntax with support for wildcards and multiple values.
+
+### Basic Syntax
+
+Rules follow the format: `key=value [key=value ...]` with three supported keys:
+
+- **`method`**: HTTP method(s) - Any HTTP method (e.g., `GET`, `POST`, `PUT`, `DELETE`), `*` (all methods), or comma-separated list
+- **`domain`**: Domain/hostname pattern - `github.com`, `*.example.com`, `*` (all domains)
+- **`path`**: URL path pattern - `/api/users`, `/api/*/users`, `*` (all paths), or comma-separated list
+
+**Key behavior**:
+
+- If a key is omitted, it matches all values
+- Multiple key-value pairs in one rule are separated by whitespace
+- Multiple rules in the allowlist are OR'd together (OR logic)
+- Default deny: if no rule matches, the request is denied
+
+**Examples**:
+
+```yaml
+allowlist:
+  - domain=github.com                                  # All methods, all paths for github.com
+  - method=GET,POST domain=api.example.com             # GET/POST to api.example.com
+  - domain=api.example.com path=/users,/posts          # Multiple paths
+  - method=GET domain=github.com path=/api/*           # All three keys
+```
+
+---
+
+## Wildcard Symbol for Domains
+
+The `*` wildcard matches domain labels (parts separated by dots).
+
+| Pattern        | Matches                                                          | Does NOT Match                                                           |
+|----------------|------------------------------------------------------------------|--------------------------------------------------------------------------|
+| `*`            | All domains                                                      | -                                                                        |
+| `github.com`   | `github.com`, `api.github.com`, `v1.api.github.com` (subdomains) | `github.io` (diff domain)                                                |
+| `*.github.com` | `api.github.com`, `v1.api.github.com` (1+ subdomain levels)      | `github.com` (base domain)                                               |
+| `api.*.com`    | `api.github.com`, `api.google.com`                               | `api.v1.github.com` (`*` in the middle matches exactly one domain label) |
+| `*.*.com`      | `api.example.com`, `api.v1.github.com`                           | -                                                                        |
+| `api.*`        | ❌ **ERROR** - Cannot end with `*`                                | -                                                                        |
+
+**Important**:
+
+- Patterns without `*` at the start automatically match subdomains
+- `*.example.com` matches one or more subdomain levels
+- Domain patterns **cannot end with asterisk**
+
+---
+
+## Wildcard Symbol for Paths
+
+The `*` wildcard matches path segments (parts separated by slashes).
+
+| Pattern        | Matches                                                    | Does NOT Match                          |
+|----------------|------------------------------------------------------------|-----------------------------------------|
+| `*`            | All paths                                                  | -                                       |
+| `/api/users`   | `/api/users`                                               | `/api/users/123` (subpaths don't match) |
+| `/api/*`       | `/api/users`, `/api/posts`                                 | `/api`                                  |
+| `/api/*/users` | `/api/v1/users`, `/api/v2/users`                           | `/api/users`, `/api/v1/v2/users`        |
+| `/*/users`     | `/api/users`, `/v1/users`                                  | `/api/v1/users`                         |
+| `/api/v1/*`    | `/api/v1/users`, `/api/v1/users/123/details` (1+ segments) | `/api/v1`                               |
+
+**Important**:
+
+- `*` matches **exactly one segment** (except at the end)
+- `*` at the **end** matches **one or more segments** (special behavior)
+- `*` must match an entire segment (cannot be part of a segment like `/api/user*`)
+
+---
+
+## Special Meaning of Wildcard at Beginning and End
+
+| Position   | Domain              | Path                  |
+|------------|---------------------|-----------------------|
+| Beginning  | 1+ subdomain levels | Exactly 1 segment     |
+| Middle     | Exactly 1 label     | Exactly 1 segment     |
+| End        | ❌ Not allowed       | 1+ segments (special) |
+| Standalone | All domains         | All paths             |
+
+---
+
+## Multipath
+
+Specify multiple paths in a single rule by separating them with commas:
+
+```yaml
+allowlist:
+  - domain=api.example.com path=/users,/posts,/comments
+  - domain=api.example.com path=/api,/api/*
+```
+
+`NOTE`: The pattern `/api/*` does not include the base path `/api`.
+To match both, use `path=/api,/api/*`.

docs/ai-coder/index.md

@@ -22,6 +22,6 @@ In cases where the IDE is secondary, such as prototyping or long-running backgro
 
 AI agents can be powerful teammates, but must be treated as untrusted and unpredictable interns as opposed to tools. Without the right controls, they can go rogue.
 
-[Agent Boundaries](./agent-boundary.md) is a new tool that offers process-level safeguards that detect and prevent destructive actions. Unlike traditional mitigation methods like firewalls, service meshes, and RBAC systems, Agent Boundaries is an agent-aware, centralized control point that can either be embedded in the same secure Coder Workspaces that enterprises already trust, or used through an open source CLI.
+[Agent Boundaries](./boundary/agent-boundary.md) is a new tool that offers process-level safeguards that detect and prevent destructive actions. Unlike traditional mitigation methods like firewalls, service meshes, and RBAC systems, Agent Boundaries is an agent-aware, centralized control point that can either be embedded in the same secure Coder Workspaces that enterprises already trust, or used through an open source CLI.
 
-To learn more about features, implementation details, and how to get started, check out the [Agent Boundary documentation](./agent-boundary.md).
+To learn more about features, implementation details, and how to get started, check out the [Agent Boundary documentation](./boundary/agent-boundary.md).

docs/ai-coder/security.md

@@ -25,4 +25,4 @@ Additional guidance and tooling is coming in future releases of Coder.
 
 ## Set Up Agent Boundaries
 
-Agent Boundaries are process-level "agent firewalls" that lets you restrict and audit what AI agents can access within Coder workspaces. To learn more about this feature, see [Agent Boundary](./agent-boundary.md).
+Agent Boundaries are process-level "agent firewalls" that lets you restrict and audit what AI agents can access within Coder workspaces. To learn more about this feature, see [Agent Boundary](./boundary/agent-boundary.md).

docs/manifest.json

@@ -972,18 +972,23 @@
 				{
 					"title": "Agent Boundaries",
 					"description": "Understanding Agent Boundaries in Coder Tasks",
-					"path": "./ai-coder/agent-boundary.md",
+					"path": "./ai-coder/boundary/agent-boundary.md",
 					"state": ["beta"],
 					"children": [
 						{
 							"title": "nsjail",
 							"description": "Documentation for Namespace Jail",
-							"path": "./ai-coder/nsjail.md"
+							"path": "./ai-coder/boundary/nsjail.md"
 						},
 						{
 							"title": "landjail",
 							"description": "Documentation for LandJail",
-							"path": "./ai-coder/landjail.md"
+							"path": "./ai-coder/boundary/landjail.md"
+						},
+						{
+							"title": "Rules Engine",
+							"description": "Documentation for the Boundary rules engine",
+							"path": "./ai-coder/boundary/rules-engine.md"
 						}
 					]
 				},