docs: migrate Guardian documentation from deprecated GuardianCheck to Intrinsics API

AGENTS.md

@@ -184,7 +184,7 @@ Intrinsics are specialized LoRA adapters that add task-specific capabilities (RA
 | `rag` | `rewrite_question(question, context, backend)` | Rewrite question into a retrieval query |
 | `rag` | `clarify_query(question, documents, context, backend)` | Generate clarification or return "CLEAR" |
 | `rag` | `find_citations(response, documents, context, backend)` | Document sentences supporting the response |
-| `rag` | `check_context_relevance(question, document, context, backend)` | Whether a document is relevant (0–1); only supported for granite-4.0, not granite-4.1 |
+| `rag` | `check_context_relevance(question, document, context, backend)` | Whether a document is relevant; returns a string label (e.g. `'relevant'`, `'partially relevant'`, `'irrelevant'`). **Granite 4.0 only — no adapter for Granite 4.1.** Use `ibm-granite/granite-4.0-micro` as the backend. |
 | `rag` | `flag_hallucinated_content(response, documents, context, backend)` | Flag potentially hallucinated sentences |
 
 ```python

docs/CONTRIBUTING_DOCS.md

@@ -202,7 +202,8 @@ Terms that **must** be linked on first use wherever they appear in guide pages (
 | `ReAct` | `#react` |
 | `RichDocument` | `#richdocument` |
 | `LiteLLM` / `LiteLLMBackend` | `#litellm--litellmbackend` |
-| `GuardianCheck` / `GuardianRisk` | `#guardiancheck` |
+| `guardian_check()` / `CRITERIA_BANK` | `#guardian_check` / `#criteria_bank` |
+| `GuardianCheck` / `GuardianRisk` *(deprecated)* | `#guardiancheck` / `#guardianrisk` |
 | `m decompose` | `#m-decompose` |
 
 Linking within the **glossary page itself** is not required (the glossary is the definition source).

docs/docs/advanced/intrinsics.md

@@ -31,7 +31,7 @@ Set up the backend once and reuse it across intrinsic calls:
 # Returns: LocalHFBackend
 from mellea.backends.huggingface import LocalHFBackend
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 ```
 
 Or, with a Granite Switch model via the OpenAI backend:
@@ -62,7 +62,7 @@ from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
 from mellea.stdlib.context import ChatContext
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 context = ChatContext().add(Message("assistant", "Hello! How can I help you?"))
 question = "What is the square root of 4?"
 
@@ -79,12 +79,13 @@ Assess whether a document is relevant to a question:
 
 ```python
 # Requires: mellea[hf]
-# Returns: float
+# Returns: str
 from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Document
 from mellea.stdlib.components.intrinsic import rag
 from mellea.stdlib.context import ChatContext
 
+# NOTE: no context_relevance adapter for Granite 4.1 — use granite-4.0-micro
 backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
 context = ChatContext()
 question = "Who is the CEO of Microsoft?"
@@ -94,7 +95,7 @@ document = Document(
 )
 
 result = rag.check_context_relevance(question, document, context, backend)
-print(result)  # False — the document does not mention the CEO
+print(result)  # 'partially relevant' — doc is about Microsoft but not its CEO
 ```
 
 ## Hallucination detection
@@ -109,7 +110,7 @@ from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
 from mellea.stdlib.context import ChatContext
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 context = (
     ChatContext()
     .add(Message("assistant", "Hello! How can I help you?"))
@@ -138,7 +139,7 @@ from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
 from mellea.stdlib.context import ChatContext
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 context = ChatContext().add(Message("user", "Who attended the meeting?"))
 documents = [
     Document("Meeting attendees: Alice, Bob, Carol."),
@@ -163,7 +164,7 @@ from mellea.stdlib.components import Message
 from mellea.stdlib.components.intrinsic import rag
 from mellea.stdlib.context import ChatContext
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 context = (
     ChatContext()
     .add(Message("assistant", "Welcome to pet questions!"))
@@ -190,7 +191,7 @@ from mellea.stdlib.components import Document, Message
 from mellea.stdlib.components.intrinsic import rag
 from mellea.stdlib.context import ChatContext
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 context = ChatContext().add(
     Message("user", "How did Murdoch expand in Australia versus New Zealand?")
 )
@@ -223,7 +224,7 @@ from mellea.backends.huggingface import LocalHFBackend
 from mellea.stdlib.components import Intrinsic, Message
 from mellea.stdlib.context import ChatContext
 
-backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+backend = LocalHFBackend(model_id="ibm-granite/granite-4.1-3b")
 
 # Register an adapter by task name
 req_adapter = CustomIntrinsicAdapter(
@@ -251,3 +252,12 @@ The `Intrinsic` component loads aLoRA adapters (falling back to LoRA) by task na
 For OpenAI backends with Granite Switch, adapters are loaded from the model's
 HuggingFace repository configuration instead of the intrinsic catalog.
 Output format is task-specific — `requirement-check` returns a likelihood score.
+
+---
+
+## Guardian Intrinsics
+
+Safety and factuality checks use a separate set of Guardian-specific intrinsics:
+`guardian_check()`, `policy_guardrails()`, `factuality_detection()`, and
+`factuality_correction()`. These are documented in the
+[Safety Guardrails](../how-to/safety-guardrails) how-to guide.

docs/docs/concepts/architecture-vs-agents.md

@@ -136,8 +136,8 @@ orchestrator:
   with [`ChatContext`](../reference/glossary#chatcontext) and the `@tool` decorator. See
   [Tools and Agents](../how-to/tools-and-agents).
 - **Guarded agents** — combine the ReACT pattern with `requirements` and
-  `GuardianCheck` to enforce safety constraints at every step. See
-  [Security and Taint Tracking](../advanced/security-and-taint-tracking).
+  [Guardian Intrinsics](../how-to/safety-guardrails) to enforce safety constraints
+  at every step.
 - **Structured outputs** — use `@generative` with Pydantic models or `Literal` types
   to enforce type-safe structured output at each step. See
   [Generative Functions](../how-to/generative-functions).
@@ -213,4 +213,4 @@ tools or steps.
 ---
 
 **See also:** [Tools and Agents](../how-to/tools-and-agents) |
-[Security and Taint Tracking](../advanced/security-and-taint-tracking)
+[Safety Guardrails](../how-to/safety-guardrails)

docs/docs/concepts/plugins.mdx

@@ -1049,4 +1049,4 @@ from mellea.plugins import (
 
 ---
 
-**See also:** [Glossary](../reference/glossary), [Tools and Agents](../how-to/tools-and-agents), [Security and Taint Tracking](../advanced/security-and-taint-tracking), [OpenTelemetry Tracing](../observability/tracing)
+**See also:** [Glossary](../reference/glossary), [Tools and Agents](../how-to/tools-and-agents), [Safety Guardrails](../how-to/safety-guardrails), [OpenTelemetry Tracing](../observability/tracing)

docs/docs/docs.json

@@ -69,6 +69,7 @@
               "how-to/configure-model-options",
               "how-to/use-images-and-vision",
               "how-to/build-a-rag-pipeline",
+              "how-to/safety-guardrails",
               "how-to/refactor-prompts-with-cli",
               "how-to/unit-test-generative-code",
               "how-to/handling-exceptions"
@@ -115,7 +116,6 @@
               "advanced/lora-and-alora-adapters",
               "advanced/prefix-caching-and-kv-blocks",
               "advanced/inference-time-scaling",
-              "advanced/security-and-taint-tracking",
               "advanced/mellea-core-internals",
               "advanced/template-formatting",
               "advanced/custom-components"
@@ -484,10 +484,6 @@
       "source": "/integrations/langchain-and-smolagents",
       "destination": "/integrations/langchain"
     },
-    {
-      "source": "/how-to/safety-guardrails",
-      "destination": "/advanced/security-and-taint-tracking"
-    },
     {
       "source": "/dev/constrained-decoding",
       "destination": "/advanced/mellea-core-internals"
@@ -631,6 +627,10 @@
     {
       "source": "/guide/m-decompose",
       "destination": "/how-to/m-decompose"
+    },
+    {
+      "source": "/advanced/security-and-taint-tracking",
+      "destination": "/how-to/safety-guardrails"
     }
   ]
 }

docs/docs/examples/index.md

@@ -62,7 +62,8 @@ to run.
 
 | Category | What it shows |
 | -------- | ------------- |
-| `safety/` | `GuardianCheck` for harm, jailbreak, profanity, social bias, violence, and groundedness; shared backend pattern |
+| `intrinsics/` | [Guardian Intrinsics](../how-to/safety-guardrails): `guardian_check()` for harm, jailbreak, social bias, groundedness; `policy_guardrails()`; `factuality_detection()` / `factuality_correction()` |
+| `safety/` | *(Examples removed — see [Guardian how-to guide](../how-to/safety-guardrails) for the current API. The `RepairTemplateStrategy` gap is tracked in [#1071](https://github.com/generative-computing/mellea/issues/1071).)* |
 
 ### Integration and deployment
 
@@ -79,7 +80,7 @@ to run.
 | Category | What it shows |
 | -------- | ------------- |
 | `aLora/` | Training aLoRA adapters for fast constraint checking; performance optimisation |
-| `intrinsics/` | Answer relevance, hallucination detection, citation validation, context relevance — specialised adapter-backed checks |
+| `intrinsics/` | *(Non-Guardian)* Answer relevance, hallucination detection, citation validation, context relevance — specialised adapter-backed checks. For Guardian safety functions see [Safety and validation](#safety-and-validation) above |
 | `granite-switch/` | Running intrinsics via OpenAI backend with Granite Switch embedded adapters |
 | `sofai/` | Two-tier sampling: fast-model iteration with escalation to a slow model; cost optimisation |