## Description We need to document, for the **1.4.x** branch of the AI module, how to *use* the current guardrails — and restructure the documentation so the single, very long `docs/developers/guardrails.md` page is split into a proper section. Today everything lives in one file (`docs/developers/guardrails.md`, linked from the nav as `Develop → Guardrails`). It mixes general/architectural information with the specifics of each built-in guardrail, which makes it hard to scan and hard to point a site builder at "how do I use guardrail X". We should split it into a **Guardrails section** where the general information gets its own page and **each built-in guardrail gets its own page**. There are currently three built-in guardrail plugins (`src/Plugin/AiGuardrail/`): | Plugin id | Label | Notes | | --- | --- | --- | | `input_length_limit` | Input Length Limit | Blocks input that exceeds a configurable character or token count limit. **Not currently documented in the existing page** — add it. | | `regexp_guardrail` | Regexp Guardrail | Deterministic; matches the last chat message against a configurable regex. | | `restrict_to_topic` | Restrict to Topic | Non-deterministic (uses an LLM); implements `NonDeterministicGuardrailInterface` + `NonStreamableGuardrailInterface`. | ## Tasks * [x] Convert `docs/developers/guardrails.md` into a section, e.g. `docs/developers/guardrails/` with an `index.md` overview plus one page per built-in guardrail. * [x] **General information page** (`guardrails/index.md`) — site-builder/usage oriented: what guardrails are, the architecture overview & execution flow, result types (`PassResult` / `StopResult` / `RewriteInputResult` / `RewriteOutputResult`), score aggregation & stop threshold, guardrail modes (pre / post / during), managing guardrails and guardrail sets in the UI (`/admin/config/ai/guardrails`) and required permissions, applying a guardrail set to input (incl. multiple sets), and global guardrails (`/admin/config/ai/guardrails/global`). * [x] **One page per built-in guardrail**, each focused on *how to use it* (what it does, when to use it, every configurable field, an example configuration): * [x] Input Length Limit (`input_length_limit`) — currently missing from the docs entirely. * [x] Regexp Guardrail (`regexp_guardrail`) — Regexp Pattern, Violation Message (`@pattern` placeholder). * [x] Restrict to Topic (`restrict_to_topic`) — Valid/Invalid Topics, AI Provider/Model, violation messages; note it is non-deterministic and calls an LLM. * [x] Decide where the developer-facing "writing a custom guardrail plugin" content lives — keep it in the general/overview page or give it its own sub-page (it covers the `#[AiGuardrail]` attribute, `ConfigurableInterface`/`PluginFormInterface`, and the `NonStreamable`/`NonDeterministic`/`Streamable` interfaces). Cross-reference the existing `create-guardrail-plugin` skill. * [x] Update the `mkdocs.yml` nav: replace the single `- Guardrails: developers/guardrails.md` entry (currently under `Develop`) with a nested `Guardrails` section listing the general page and each guardrail page. * [x] Add redirects or keep the old path working so existing links to `developers/guardrails.md` do not 404 (e.g. via the mkdocs redirect plugin or by leaving `guardrails.md` as a stub that points to the new index). * [x] Ensure no content is lost in the split — every section currently in `guardrails.md` should land somewhere in the new structure. ## Acceptance criteria * The guardrails documentation in 1.4.x is split into a section: one general/overview page plus a dedicated page per built-in guardrail. * All three built-in guardrails are documented, including `input_length_limit`, which is currently undocumented. * Each guardrail page documents its purpose and all configurable fields with an example. * The `mkdocs.yml` navigation reflects the new section and builds cleanly (`mkdocs build` with no warnings about the changed paths). * Existing links to the old single-page URL still resolve (redirect or stub). * No information from the original page is dropped. ## Testing instructions *(added by implementor before review)* 1. Build the docs locally (`mkdocs serve` / `mkdocs build`) and confirm the new Guardrails section renders with the general page and one page per guardrail, with working navigation and no broken internal links. ## Related issues *(optional)* <!-- Link related issues here. -->