docs: initial Guardian documentation migration from deprecated GuardianCheck to Intrinsics API

Migrates docs, examples, and cross-links from the deprecated GuardianCheck/GuardianRisk
API to the current Guardian Intrinsics API (guardian_check(), policy_guardrails(),
factuality_detection(), factuality_correction()).

- New how-to/safety-guardrails.md: full reference for all four Intrinsic functions,
  CRITERIA_BANK keys, and the target_role="user" input-gating pattern
- Tutorial 04 steps 4–7 rewritten to use Intrinsics; prerequisites updated
- Glossary: 5 new entries; GuardianCheck/GuardianRisk entries marked deprecated
- Deprecation banners added to security-and-taint-tracking.md and three example files
- docs.json: safety-guardrails added to nav; temporary redirect removed
- Cross-links updated in intrinsics.md, index.mdx, build-a-rag-pipeline.md,
  use-context-and-sessions.md, common-errors.md, architecture-vs-agents.md, plugins.mdx

Partially addresses #639, #802.

Assisted-by: Claude Code

Author: planetf1

docs/docs/advanced/intrinsics.md

@@ -209,3 +209,12 @@ print(out)  # {"requirement_likelihood": 1.0}
 
 The `Intrinsic` component loads aLoRA adapters (falling back to LoRA) by task name.
 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/advanced/security-and-taint-tracking.md

@@ -4,6 +4,13 @@ description: "Use GuardianCheck with IBM Granite Guardian to validate LLM output
 # diataxis: how-to
 ---
 
+> **Deprecated API.** The `GuardianCheck` class documented here is deprecated as
+> of Mellea v0.4 and will emit `DeprecationWarning` on use. For new code, use the
+> [Guardian Intrinsics](../how-to/safety-guardrails) — `guardian_check()`,
+> `policy_guardrails()`, `factuality_detection()`, and `factuality_correction()` —
+> which are faster, require no separate Guardian model pull, and produce consistent
+> structured output.
+
 **Prerequisites:** [Instruct, Validate, Repair](../concepts/instruct-validate-repair)
 complete, `pip install mellea`, Ollama running locally with a Granite Guardian model
 pulled.

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

@@ -135,8 +135,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).
@@ -212,4 +212,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

@@ -1003,4 +1003,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](../evaluation-and-observability/opentelemetry-tracing)

docs/docs/docs.json

@@ -68,6 +68,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"
@@ -483,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"

docs/docs/examples/index.md

@@ -60,7 +60,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/` | *(Deprecated)* `GuardianCheck` examples — see `intrinsics/` for the current API |
 
 ### Integration and deployment
 

docs/docs/guide/CONTRIBUTING.md

@@ -208,7 +208,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/how-to/build-a-rag-pipeline.md

@@ -30,7 +30,7 @@ Embedding model  →  vector search  →  top-k candidates
                                             |
                                             v
                                        Final answer
-                              (optional: GuardianCheck groundedness)
+                              (optional: guardian_check groundedness)
 ```
 
 ---
@@ -168,32 +168,34 @@ answer = m.instruct(
 
 ## Step 5: Check groundedness (optional)
 
-After generation, use [`GuardianCheck`](../reference/glossary#guardiancheck) with `GuardianRisk.GROUNDEDNESS` to
-verify the answer does not hallucinate beyond the retrieved documents:
+After generation, use [`guardian_check()`](../how-to/safety-guardrails) with
+`criteria="groundedness"` to verify the answer does not hallucinate beyond the
+retrieved documents. This requires `pip install "mellea[hf]"`:
 
 ```python
-from mellea.stdlib.requirements.safety.guardian import GuardianCheck, GuardianRisk
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.components import Message
+from mellea.stdlib.components.intrinsic import guardian
+from mellea.stdlib.context import ChatContext
 
-groundedness_check = GuardianCheck(
-    GuardianRisk.GROUNDEDNESS,
-    backend_type="ollama",
-    ollama_url="http://localhost:11434",
-    context_text="\n\n".join(relevant),
+guardian_backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+
+eval_ctx = (
+    ChatContext()
+    .add(Message("user", f"Document: {chr(10).join(relevant)}"))
+    .add(Message("assistant", str(answer)))
 )
 
-results = m.validate([groundedness_check])
-if results[0]._result:
-    print("Grounded answer:", str(answer))
+score = guardian.guardian_check(eval_ctx, guardian_backend, criteria="groundedness")
+if score < 0.5:
+    print(f"Grounded answer (score: {score:.4f}):", str(answer))
 else:
-    print("Answer may contain hallucinated content:", results[0]._reason)
+    print(f"Groundedness risk detected (score: {score:.4f})")
 ```
 
-Pass the same text to `context_text` that you used in `grounding_context` —
-this ensures the groundedness model evaluates the answer against exactly what
-the generator was given.
-
-> **Backend note:** `GuardianCheck` requires `granite3-guardian:2b` pulled in Ollama.
-> Run `ollama pull granite3-guardian:2b` before using it.
+Include the same documents in the evaluation context that you passed to
+`grounding_context` — this ensures the groundedness model evaluates the answer
+against exactly what the generator was given.
 
 ---
 
@@ -204,8 +206,11 @@ from faiss import IndexFlatIP
 from sentence_transformers import SentenceTransformer
 
 from mellea import generative, start_session
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.components import Message
+from mellea.stdlib.components.intrinsic import guardian
+from mellea.stdlib.context import ChatContext
 from mellea.stdlib.requirements import req, simple_validate
-from mellea.stdlib.requirements.safety.guardian import GuardianCheck, GuardianRisk
 
 
 @generative
@@ -226,6 +231,9 @@ def search(query: str, docs: list[str], index: IndexFlatIP,
     return [docs[i] for i in indices[0]]
 
 
+guardian_backend = LocalHFBackend(model_id="ibm-granite/granite-4.0-micro")
+
+
 def rag(docs: list[str], query: str) -> str | None:
     embedding_model = SentenceTransformer("all-MiniLM-L6-v2")
     index = build_index(docs, embedding_model)
@@ -245,14 +253,14 @@ def rag(docs: list[str], query: str) -> str | None:
         requirements=[req("Answer only from the provided documents.")],
     )
 
-    results = m.validate([GuardianCheck(
-        GuardianRisk.GROUNDEDNESS,
-        backend_type="ollama",
-        ollama_url="http://localhost:11434",
-        context_text="\n\n".join(relevant),
-    )])
-    if not results[0]._result:
-        print("Warning: groundedness check failed:", results[0]._reason)
+    eval_ctx = (
+        ChatContext()
+        .add(Message("user", f"Document: {chr(10).join(relevant)}"))
+        .add(Message("assistant", str(answer)))
+    )
+    score = guardian.guardian_check(eval_ctx, guardian_backend, criteria="groundedness")
+    if score >= 0.5:
+        print(f"Warning: groundedness risk detected (score: {score:.4f})")
 
     return str(answer)
 ```
@@ -267,7 +275,7 @@ def rag(docs: list[str], query: str) -> str | None:
 | `is_relevant` docstring | How strictly the filter interprets relevance | Adjust phrasing to match your domain |
 | `grounding_context` key names | Tracing and debugging in spans | Use descriptive names in production |
 | `requirements` on `m.instruct()` | Answer length, citation, tone | Add after baseline quality is good |
-| GuardianCheck `context_text` | What the groundedness model checks against | Match exactly what you pass to `grounding_context` |
+| `guardian_check` document context | What the groundedness model checks against | Match exactly what you pass to `grounding_context` |
 
 ---