Add policy management documentation

.github/workflows/codeql.yml

@@ -22,8 +22,8 @@ jobs:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
-      - uses: github/codeql-action/init@v2
+      - uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
-      - uses: github/codeql-action/autobuild@v2
-      - uses: github/codeql-action/analyze@v2
+      - uses: github/codeql-action/autobuild@v3
+      - uses: github/codeql-action/analyze@v3

.github/workflows/trivy.yaml

@@ -26,6 +26,6 @@ jobs:
           ignore-unfixed: true
           #severity: 'CRITICAL,HIGH'
       - name: Upload Trivy scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v2
+        uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: 'trivy-results.sarif'

generated/routes.json

@@ -85,7 +85,7 @@
   },
   "/getting-started/advanced-config/sandboxing": {
     "relPath": "/getting-started/advanced-config/sandboxing.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/getting-started/advanced-config/network-configuration": {
     "relPath": "/getting-started/advanced-config/network-configuration.md",
@@ -105,11 +105,11 @@
   },
   "/api-reference/kubernetes/management-api-reference": {
     "relPath": "/api-reference/kubernetes/management-api-reference.md",
-    "lastmod": "2026-06-10T12:45:04.000Z"
+    "lastmod": "2026-08-13T15:31:21.000Z"
   },
   "/api-reference/kubernetes/agent-api-reference": {
     "relPath": "/api-reference/kubernetes/agent-api-reference.md",
-    "lastmod": "2026-06-10T12:45:04.000Z"
+    "lastmod": "2026-08-11T20:00:52.000Z"
   },
   "/api-reference/graphql": {
     "relPath": "/api-reference/graphql.md",
@@ -121,11 +121,11 @@
   },
   "/api-reference/terraform": {
     "relPath": "/api-reference/terraform/index.md",
-    "lastmod": "2026-08-04T13:27:26.025Z"
+    "lastmod": "2026-08-04T15:01:58.000Z"
   },
   "/api-reference/terraform/pulumi": {
     "relPath": "/api-reference/terraform/pulumi.md",
-    "lastmod": "2026-08-04T13:27:26.046Z"
+    "lastmod": "2026-08-04T15:01:58.000Z"
   },
   "/plural-features": {
     "relPath": "/plural-features/index.md",
@@ -137,23 +137,23 @@
   },
   "/plural-features/continuous-deployment/management-controller": {
     "relPath": "/plural-features/continuous-deployment/management-controller/index.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/plural-features/continuous-deployment/management-controller/deployment-settings": {
     "relPath": "/plural-features/continuous-deployment/management-controller/deployment-settings.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/plural-features/continuous-deployment/deployment-operator": {
     "relPath": "/plural-features/continuous-deployment/deployment-operator/index.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/plural-features/continuous-deployment/deployment-operator/agent-configuration": {
     "relPath": "/plural-features/continuous-deployment/deployment-operator/agent-configuration.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/plural-features/continuous-deployment/deployment-operator/custom-health": {
     "relPath": "/plural-features/continuous-deployment/deployment-operator/custom-health.md",
-    "lastmod": "2026-08-13T15:06:28.330Z"
+    "lastmod": "2026-08-13T15:30:45.000Z"
   },
   "/plural-features/continuous-deployment/git-service": {
     "relPath": "/plural-features/continuous-deployment/git-service.md",
@@ -173,11 +173,11 @@
   },
   "/plural-features/continuous-deployment/service-templating": {
     "relPath": "/plural-features/continuous-deployment/service-templating/index.md",
-    "lastmod": "2026-08-04T13:27:26.172Z"
+    "lastmod": "2026-08-29T16:19:38.379Z"
   },
   "/plural-features/continuous-deployment/service-templating/supporting-liquid-filters": {
     "relPath": "/plural-features/continuous-deployment/service-templating/supporting-liquid-filters.md",
-    "lastmod": "2026-08-04T13:27:26.192Z"
+    "lastmod": "2026-08-29T16:19:38.402Z"
   },
   "/plural-features/continuous-deployment/lua": {
     "relPath": "/plural-features/continuous-deployment/lua.md",
@@ -221,15 +221,15 @@
   },
   "/plural-features/stacks-iac-management": {
     "relPath": "/plural-features/stacks-iac-management/index.md",
-    "lastmod": "2026-07-15T09:31:13.000Z"
+    "lastmod": "2026-08-04T15:01:58.000Z"
   },
   "/plural-features/stacks-iac-management/customize-runners": {
     "relPath": "/plural-features/stacks-iac-management/customize-runners.md",
     "lastmod": "2025-03-12T14:59:41.000Z"
   },
   "/plural-features/stacks-iac-management/pulumi": {
     "relPath": "/plural-features/stacks-iac-management/pulumi.md",
-    "lastmod": "2026-07-15T09:31:13.000Z"
+    "lastmod": "2026-08-04T15:01:58.000Z"
   },
   "/plural-features/stacks-iac-management/pr-workflow": {
     "relPath": "/plural-features/stacks-iac-management/pr-workflow.md",
@@ -293,7 +293,7 @@
   },
   "/plural-features/plural-ai/ai-agent/configure-agent": {
     "relPath": "/plural-features/plural-ai/ai-agent/configure-agent.md",
-    "lastmod": "2026-03-04T02:33:39.000Z"
+    "lastmod": "2026-08-29T16:16:14.000Z"
   },
   "/plural-features/plural-ai/ai-agent/remote-browser": {
     "relPath": "/plural-features/plural-ai/ai-agent/remote-browser.md",
@@ -345,40 +345,60 @@
   },
   "/plural-features/workbenches": {
     "relPath": "/plural-features/workbenches/index.md",
-    "lastmod": "2026-07-31T10:05:04.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/configuration": {
     "relPath": "/plural-features/workbenches/configuration.md",
-    "lastmod": "2026-07-31T10:05:04.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/coding-agent": {
     "relPath": "/plural-features/workbenches/coding-agent.md",
     "lastmod": "2026-05-27T21:33:58.000Z"
   },
   "/plural-features/workbenches/tools": {
     "relPath": "/plural-features/workbenches/tools.md",
-    "lastmod": "2026-07-31T10:05:04.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/tools/datadog": {
     "relPath": "/plural-features/workbenches/tools/datadog.md",
-    "lastmod": "2026-07-31T10:05:04.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/running-jobs": {
     "relPath": "/plural-features/workbenches/running-jobs.md",
-    "lastmod": "2026-07-31T10:05:04.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/automation": {
     "relPath": "/plural-features/workbenches/automation.md",
-    "lastmod": "2026-07-30T14:01:51.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/follow-up-automation": {
     "relPath": "/plural-features/workbenches/follow-up-automation.md",
-    "lastmod": "2026-07-30T15:19:23.000Z"
+    "lastmod": "2026-08-06T15:20:26.000Z"
   },
   "/plural-features/workbenches/use-cases": {
     "relPath": "/plural-features/workbenches/use-cases.md",
     "lastmod": "2026-05-27T21:33:58.000Z"
   },
+  "/plural-features/policy-management": {
+    "relPath": "/plural-features/policy-management/index.md",
+    "lastmod": "2026-08-29T16:16:14.000Z"
+  },
+  "/plural-features/policy-management/stack-policies": {
+    "relPath": "/plural-features/policy-management/stack-policies.md",
+    "lastmod": "2026-08-29T16:16:14.000Z"
+  },
+  "/plural-features/policy-management/workbench-policies": {
+    "relPath": "/plural-features/policy-management/workbench-policies.md",
+    "lastmod": "2026-08-29T16:16:14.000Z"
+  },
+  "/plural-features/policy-management/simulating-policies": {
+    "relPath": "/plural-features/policy-management/simulating-policies.md",
+    "lastmod": "2026-08-29T16:16:14.000Z"
+  },
+  "/plural-features/policy-management/common-use-cases": {
+    "relPath": "/plural-features/policy-management/common-use-cases.md",
+    "lastmod": "2026-08-29T16:16:14.000Z"
+  },
   "/plural-features/observability": {
     "relPath": "/plural-features/observability/index.md",
     "lastmod": "2025-05-10T04:27:39.000Z"
@@ -557,7 +577,7 @@
   },
   "/deployments/sandboxing": {
     "relPath": "/getting-started/advanced-config/sandboxing.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/deployments/network-configuration": {
     "relPath": "/getting-started/advanced-config/network-configuration.md",
@@ -569,11 +589,11 @@
   },
   "/deployments/operator/architecture": {
     "relPath": "/plural-features/continuous-deployment/deployment-operator/index.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/plural-features/continuous-deployment/deployment-operator/deployment-settings": {
     "relPath": "/plural-features/continuous-deployment/management-controller/deployment-settings.md",
-    "lastmod": "2026-06-26T10:42:27.000Z"
+    "lastmod": "2026-08-06T14:42:58.000Z"
   },
   "/deployments/operator/git-service": {
     "relPath": "/plural-features/continuous-deployment/git-service.md",
@@ -625,7 +645,7 @@
   },
   "/deployments/stacks": {
     "relPath": "/plural-features/stacks-iac-management/index.md",
-    "lastmod": "2026-07-15T09:31:13.000Z"
+    "lastmod": "2026-08-04T15:01:58.000Z"
   },
   "/service-catalog/creation": {
     "relPath": "/plural-features/service-catalog/creation.md",
@@ -697,10 +717,10 @@
   },
   "/management-api-reference": {
     "relPath": "/api-reference/kubernetes/management-api-reference.md",
-    "lastmod": "2026-06-10T12:45:04.000Z"
+    "lastmod": "2026-08-13T15:31:21.000Z"
   },
   "/agent-api-reference": {
     "relPath": "/api-reference/kubernetes/agent-api-reference.md",
-    "lastmod": "2026-06-10T12:45:04.000Z"
+    "lastmod": "2026-08-11T20:00:52.000Z"
   }
 }

package.json

@@ -42,12 +42,14 @@
     "@react-stately/list": "3.8.1",
     "@react-stately/select": "3.5.1",
     "@react-stately/selection": "3.19.0",
+    "@styra/highlightjs-rego": "^0.1.2",
     "chroma-js": "2.4.2",
     "classnames": "2.3.2",
     "deep-freeze": "0.0.1",
     "fuse.js": "6.6.2",
     "graphql": "16.6.0",
     "gray-matter": "4.0.3",
+    "highlight.js": "11.9.0",
     "honorable": "0.194.0",
     "honorable-theme-default": "0.77.0",
     "htmlparser2": "9.1.0",

pages/_app.tsx

@@ -25,6 +25,7 @@ import { useRouter } from 'next/router'
 import { until } from '@open-draft/until'
 import { MarkdocContextProvider } from '@pluralsh/design-system/dist/markdoc'
 import { SSRProvider } from '@react-aria/ssr'
+import '@src/highlight'
 import '@src/styles/globals.css'
 import styled, { ThemeProvider as StyledThemeProvider } from 'styled-components'
 import { SWRConfig } from 'swr'

pages/plural-features/plural-ai/ai-agent/configure-agent.md

@@ -34,6 +34,19 @@ spec:
 
 Supported runtime types are `CLAUDE`, `OPENCODE`, and `GEMINI`.
 
+## Optional: Enable codebase memory persistence
+
+Agent runtimes include the `codebase-memory-mcp` server for graph-backed code search. By default, its indexes are stored only in the agent pod cache and generated `.codebase-memory/` artifacts are excluded from commits.
+
+Set `spec.memory: true` to enable team-shared memory persistence by default:
+
+```yaml
+spec:
+  memory: true
+```
+
+When enabled, agents index repositories with persistent artifact export enabled, allowing `.codebase-memory/graph.db.zst` and the related `.gitattributes` update to be committed so future runs can bootstrap from the shared graph. Leave this unset or `false` if you want every run to keep its codebase-memory index local to the runtime cache.
+
 ## Tune runtime resources
 
 `AgentRuntime` accepts a pod template so you can set CPU/memory requests and limits for the agent container. Use the `default` container name to target the main agent container.

pages/plural-features/policy-management/common-use-cases.md

@@ -0,0 +1,94 @@
+---
+title: Common policy use cases
+description: Patterns for governing workbench tools and infrastructure stack approvals
+---
+
+Policies are most useful when they encode a narrow, explainable rule around a high-impact operation. Start with guardrails that can be evaluated from explicit input fields, then expand coverage as you observe real evaluations in the simulator.
+
+## Workbench policies
+
+### Extend authorization for external tools
+
+Many external systems have coarse authorization models: a credential may allow access to an entire observability account, log index, or API even when a user only needs a subset. Workbench policies can add request-level controls without issuing a separate credential for every user and use case.
+
+Examples include:
+
+- Restricting production log searches to an incident-response group
+- Denying queries against sensitive audit or customer-data indices
+- Limiting observability queries to approved accounts, services, or time ranges
+- Preventing write operations through an external API while permitting reads
+
+Policy input includes both the actor and tool arguments, allowing the decision to account for who is requesting the action and exactly what the agent plans to send.
+
+### Increase autonomy with safe-action allowlists
+
+Agents are most useful when routine, reversible actions can proceed without waiting for a human. Add `approve` rules for a well-defined set of safe operations while leaving everything else on the normal approval path.
+
+Examples include:
+
+- Approving restarts of stateless workloads outside protected namespaces
+- Approving read-only diagnostic or observability calls
+- Allowing an SRE group to update non-production resources
+- Automatically posting summaries to a designated incident channel
+
+Prefer explicit conditions on tool name and arguments over broad actor-only approvals. A narrow allowlist keeps autonomy predictable as new tools and operations are added.
+
+### Guarantee operational best practices
+
+Workbench policies apply the same safeguards to every matching workbench, regardless of its prompt or the model running it.
+
+Examples include:
+
+- Blocking Kubernetes deletes in system namespaces
+- Requiring production mutations to originate from an approved group
+- Denying changes that omit required ownership, ticket, or incident metadata
+- Preventing access to regulated datasets from general-purpose workbenches
+
+Use binding policies to attach these guardrails automatically based on workbench naming or metadata conventions.
+
+## Stack policies
+
+### Enforce change-management requirements
+
+Inspect the actor, stack, commit, run type, and plan to require the evidence your organization expects before infrastructure changes proceed.
+
+Examples include:
+
+- Rejecting production applies without an approved change reference
+- Restricting destroy runs to a designated operations group
+- Requiring sensitive stacks to follow a specific repository or branch workflow
+- Blocking changes during a freeze window when the required context is present in policy input
+
+### Streamline approval of known-safe plans
+
+Stack policies can automatically approve plans that fit a constrained risk profile and leave all other plans to a human or AI reviewer.
+
+Examples include:
+
+- Approving tag-only updates
+- Approving additive changes to an allowed set of resource types
+- Approving non-production plans below a defined size
+- Approving EKS plans only when they do not destroy clusters or node groups and do not update the control-plane version
+
+Model the safe case explicitly. If a plan does not satisfy every condition, return no approval and let the configured approval workflow handle it.
+
+### Enforce compliance at scale
+
+Evaluate every matching Terraform plan against controls derived from internal standards or regulatory frameworks.
+
+Examples include:
+
+- Requiring encryption and approved key-management configuration
+- Denying public network exposure for protected workloads
+- Enforcing required tags, retention settings, and backup policies
+- Restricting resource types, providers, regions, or machine classes
+
+Combine reusable stack policies with binding policies to apply controls across projects and stack families. Include a clear denial message that identifies the failed requirement and the expected remediation.
+
+## Design recommendations
+
+- Keep each rule focused on one decision and provide a specific reason.
+- Use `deny` for requirements that must never be bypassed.
+- Use `approve` only for operations whose complete safe boundary can be expressed from the available input.
+- Leave uncertain cases undecided so existing human or AI approval remains in control.
+- Test boundary conditions in Rego and replay representative live inputs in the [policy simulator](/plural-features/policy-management/simulating-policies).