docs: move glossary to reference section (#892)

Signed-off-by: Paul S. Schweigert <paul@paulschweigert.com>

Author: psschwei

docs/docs/advanced/custom-components.md

@@ -32,7 +32,7 @@ less boilerplate.
 
 ## The Component Protocol
 
-[`Component`](../guide/glossary#component) is a `Protocol` generic over `S`, the return type produced when the
+[`Component`](../reference/glossary#component) is a `Protocol` generic over `S`, the return type produced when the
 component parses LLM output:
 
 ```python
@@ -43,10 +43,10 @@ The protocol has three required methods and one public method that wraps `_parse
 
 | Method | Signature | Purpose |
 | ------ | --------- | ------- |
-| `parts()` | `-> list[Component \| CBlock]` | Returns child components and [`CBlock`](../guide/glossary#cblock) content blocks |
+| `parts()` | `-> list[Component \| CBlock]` | Returns child components and [`CBlock`](../reference/glossary#cblock) content blocks |
 | `format_for_llm()` | `-> TemplateRepresentation \| str` | Formats the component for LLM consumption |
 | `_parse()` | `(computed: ModelOutputThunk) -> S` | Parses LLM output into the return type `S` |
-| `parse()` | `(computed: ModelOutputThunk) -> S` | Public wrapper — catches exceptions as [`ComponentParseError`](../guide/glossary#componentparseerror) |
+| `parse()` | `(computed: ModelOutputThunk) -> S` | Public wrapper — catches exceptions as [`ComponentParseError`](../reference/glossary#componentparseerror) |
 
 You implement `parts()`, `format_for_llm()`, and `_parse()`. You do not override
 `parse()` — the base implementation calls `_parse()` and wraps any exception in a
@@ -135,7 +135,7 @@ with start_session() as m:
 ## Using TemplateRepresentation for Jinja2-based rendering
 
 For components that need model-specific prompt formatting, return a
-[`TemplateRepresentation`](../guide/glossary#templaterepresentation) from `format_for_llm()` instead of a plain string.
+[`TemplateRepresentation`](../reference/glossary#templaterepresentation) from `format_for_llm()` instead of a plain string.
 `TemplateRepresentation` is a dataclass with these fields:
 
 | Field | Type | Purpose |

docs/docs/advanced/mellea-core-internals.md

@@ -41,7 +41,7 @@ boundaries let you control exactly where the tokeniser makes splits.
 
 A `Component` is a declarative structure that can depend on other `Component`s or
 `CBlock`s. Components are the unit of composition in Mellea. `Message`,
-[`Instruction`](../guide/glossary#instruction), `@mify` objects, and `@generative` functions all produce `Component`s.
+[`Instruction`](../reference/glossary#instruction), `@mify` objects, and `@generative` functions all produce `Component`s.
 
 ### `ModelOutputThunk`
 
@@ -220,7 +220,7 @@ in parallel if the backend supports it), and returns `z`'s result.
 
 ### TemplateFormatter
 
-Mellea formats Python objects into LLM-readable text using a [`TemplateFormatter`](../guide/glossary#templateformatter).
+Mellea formats Python objects into LLM-readable text using a [`TemplateFormatter`](../reference/glossary#templateformatter).
 It uses Jinja2 templates stored in a `templates/prompts/` directory. Each
 component class can have its own template, looked up by class name.
 
@@ -247,7 +247,7 @@ The formatter returns the template from the deepest matching directory. A model
 of `ibm-granite/granite-3.2-8b-instruct` matches `granite/granite-3-2/instruct`
 but not `ibm/` — only one path should match in any given templates directory.
 
-### [`TemplateRepresentation`](../guide/glossary#templaterepresentation)
+### [`TemplateRepresentation`](../reference/glossary#templaterepresentation)
 
 Each component's `format_for_llm()` method returns either a string or a
 `TemplateRepresentation`. The `TemplateRepresentation` specifies:

docs/docs/advanced/security-and-taint-tracking.md

@@ -40,7 +40,7 @@ print(f"Content is safe: {results[0]._result}")
 ```
 
 `thinking=True` enables extended reasoning mode in the Guardian model for more
-accurate results. `results` is a list of [`ValidationResult`](../guide/glossary#validationresult) objects — one per
+accurate results. `results` is a list of [`ValidationResult`](../reference/glossary#validationresult) objects — one per
 requirement passed to `validate()`.
 
 ## Risk types

docs/docs/community/building-extensions.md

@@ -25,7 +25,7 @@ Choose the pathway that fits the scope of your work:
 
 ## Custom requirements
 
-A [`Requirement`](../guide/glossary#requirement) validates a generation against a
+A [`Requirement`](../reference/glossary#requirement) validates a generation against a
 criterion. You can provide a Python function for deterministic checks, or rely on
 LLM-as-a-Judge for semantic validation.
 
@@ -92,7 +92,7 @@ For deeper validation patterns, see [Write Custom Verifiers](../how-to/write-cus
 
 ## Custom components
 
-A [`Component`](../guide/glossary#component) is a composite data structure that an LLM
+A [`Component`](../reference/glossary#component) is a composite data structure that an LLM
 can read and write. Implement the `Component` protocol by providing `parts`,
 `format_for_llm`, and `_parse`:
 
@@ -141,7 +141,7 @@ For a full walkthrough of the Component protocol and templating system, see
 
 ## Custom sampling strategies
 
-A [`SamplingStrategy`](../guide/glossary#sampling-strategy) controls how Mellea
+A [`SamplingStrategy`](../reference/glossary#sampling-strategy) controls how Mellea
 generates and validates outputs — for example, rejection sampling, best-of-n, or
 beam search. Subclass `SamplingStrategy` and implement `sample`:
 
@@ -226,7 +226,7 @@ For built-in strategies and advanced patterns, see
 
 ## Custom backends
 
-A [`Backend`](../guide/glossary#backend) connects Mellea to an inference provider.
+A [`Backend`](../reference/glossary#backend) connects Mellea to an inference provider.
 Subclass the abstract `Backend` class from `mellea.core.backend` and implement
 the two abstract methods:
 

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

@@ -132,7 +132,7 @@ Mellea also supports building agentic programs directly, without an external
 orchestrator:
 
 - **ReACT loops** — implement thought/action/observation cycles using `m.chat()`
-  with [`ChatContext`](../guide/glossary#chatcontext) and the `@tool` decorator. See
+  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

docs/docs/concepts/context-and-sessions.md

@@ -4,8 +4,8 @@ description: "How Component, Backend, Context, and Session fit together in Melle
 # diataxis: explanation
 ---
 
-Every call to an LLM in Mellea passes through four layers: [**Component**](../guide/glossary#component), [**Backend**](../guide/glossary#backend),
-[**Context**](../guide/glossary#context), and **Session**. Understanding how these fit together explains both why
+Every call to an LLM in Mellea passes through four layers: [**Component**](../reference/glossary#component), [**Backend**](../reference/glossary#backend),
+[**Context**](../reference/glossary#context), and **Session**. Understanding how these fit together explains both why
 Mellea is structured the way it is and how to extend it effectively.
 
 > **Looking to use this in code?** See [Context and Sessions](../how-to/use-context-and-sessions) for practical examples and session extension patterns.
@@ -30,7 +30,7 @@ raw text or a parsed representation of a model output.
 ### Backends
 
 A `Backend` takes a `Component`, formats it into a prompt, sends it to an LLM, and
-returns the model output as a [`ModelOutputThunk`](../guide/glossary#modeloutputthunk). The `Thunk` is a lazy wrapper: it
+returns the model output as a [`ModelOutputThunk`](../reference/glossary#modeloutputthunk). The `Thunk` is a lazy wrapper: it
 holds the raw model output and parses it on access (via `.value` or `str()`).
 
 The backend is responsible for:
@@ -52,15 +52,15 @@ The context serves two purposes:
 
 1. **Prompt construction** — the backend calls `ctx.view_for_generation()` to get
    the components that should appear in the prompt. For `ChatContext`, this includes
-   all prior turns. For [`SimpleContext`](../guide/glossary#simplecontext), it includes only the current instruction.
+   all prior turns. For [`SimpleContext`](../reference/glossary#simplecontext), it includes only the current instruction.
 
 2. **Validation** — during the IVR loop, requirement validators receive the
    `Context` object. They can call `ctx.last_output()` to inspect the most recent
    model output, or examine the full history for more complex checks.
 
 ### Sessions
 
-[`MelleaSession`](../guide/glossary#melleasession) is the developer-facing layer. It wraps a backend and a context,
+[`MelleaSession`](../reference/glossary#melleasession) is the developer-facing layer. It wraps a backend and a context,
 exposes the `instruct()`, `chat()`, `validate()`, and other methods you use in your
 code, and handles the bookkeeping that ties components, context updates, and backend
 calls together.
@@ -201,7 +201,7 @@ print(last.value)
 turn = m.ctx.last_turn()
 ```
 
-`last_turn()` returns a [`ContextTurn`](../guide/glossary#contextturn) with `.input` and `.output` fields. It is
+`last_turn()` returns a [`ContextTurn`](../reference/glossary#contextturn) with `.input` and `.output` fields. It is
 useful for observability or when you need to log exactly what the model received and
 produced.
 

docs/docs/concepts/generative-functions.md

@@ -6,7 +6,7 @@ description: "How the @generative decorator turns a Python function signature in
 
 In classical programming, a pure function takes inputs and produces outputs deterministically.
 In a generative program, a function can have the same interface but delegate its implementation
-to an LLM. Mellea calls these [**generative functions**](../guide/glossary#generative-function) and provides the [`@generative`](../guide/glossary#generative) decorator
+to an LLM. Mellea calls these [**generative functions**](../reference/glossary#generative-function) and provides the [`@generative`](../reference/glossary#generative) decorator
 to define them.
 
 > **Looking to use this in code?** See [Generative Functions](../how-to/generative-functions) for practical examples and API details.

docs/docs/concepts/generative-programming.md

@@ -4,7 +4,7 @@ description: "The ideas behind Mellea — what generative programs are, why they
 # diataxis: explanation
 ---
 
-A [_generative program_](../guide/glossary#generative-program) is any program that contains calls to an LLM. This covers
+A [_generative program_](../reference/glossary#generative-program) is any program that contains calls to an LLM. This covers
 everything from a simple prompt wrapper to a complex multi-step reasoning system.
 The term is deliberately broad: what matters is not how many LLM calls a program
 makes, but the structural challenges that arise when you combine stochastic LLM
@@ -32,7 +32,7 @@ unchecked through the system.
 
 ## Requirements as the core tool
 
-The primary mechanism Mellea provides for managing stochasticity is [_requirements_](../guide/glossary#requirement).
+The primary mechanism Mellea provides for managing stochasticity is [_requirements_](../reference/glossary#requirement).
 A requirement is a validation function that checks whether an LLM output meets a
 specified criterion:
 
@@ -51,7 +51,7 @@ result = m.instruct(
 ```
 
 When the model's output fails a requirement, Mellea can retry the generation with
-feedback — the [_Instruct–Validate–Repair_ (IVR)](../guide/glossary#ivr-instruct-validate-repair) loop. This transforms a
+feedback — the [_Instruct–Validate–Repair_ (IVR)](../reference/glossary#ivr-instruct-validate-repair) loop. This transforms a
 probabilistically unreliable call into one with measurable, controllable reliability:
 set a `loop_budget` and the probability of the output satisfying your requirements
 approaches 1 as budget increases.
@@ -66,7 +66,7 @@ Not all requirements can be checked cheaply. A constraint like "this JSON is
 syntactically valid" can be verified in microseconds; a constraint like "this
 answer is grounded in the provided context" may require a second model call.
 
-Mellea's [sampling strategies](../guide/glossary#sampling-strategy) control how retries work:
+Mellea's [sampling strategies](../reference/glossary#sampling-strategy) control how retries work:
 
 - **`RejectionSamplingStrategy`** — retry until a requirement passes or the budget
   is exhausted. The simplest strategy; good for cheap validators.
@@ -100,10 +100,10 @@ large enough to exceed model limits or degrade output quality.
 
 Mellea addresses this through explicit context management:
 
-- **[`SimpleContext`](../guide/glossary#context)** (default) resets history on each call. The model sees only
+- **[`SimpleContext`](../reference/glossary#context)** (default) resets history on each call. The model sees only
   the current instruction. This is usually the right choice for independent calls.
-- **[`ChatContext`](../guide/glossary#context)** preserves history for multi-turn conversations.
-- **[Components](../guide/glossary#component)** ([`@mify`](../guide/glossary#mify--mify), [`@generative`](../guide/glossary#generative)) encapsulate the context needed for a
+- **[`ChatContext`](../reference/glossary#context)** preserves history for multi-turn conversations.
+- **[Components](../reference/glossary#component)** ([`@mify`](../reference/glossary#mify--mify), [`@generative`](../reference/glossary#generative)) encapsulate the context needed for a
   single call, keeping context management compositional rather than global.
 
 ## Mellea's position in the ecosystem

docs/docs/concepts/instruct-validate-repair.md

@@ -7,10 +7,10 @@ description: "How instruct(), requirements, and the IVR loop work in Mellea."
 **Prerequisites:** [Quick Start](../getting-started/quickstart) complete,
 `pip install mellea`, Ollama running locally.
 
-`instruct()` is the primary API in Mellea. It builds a structured [`Instruction`](../guide/glossary#component)
+`instruct()` is the primary API in Mellea. It builds a structured [`Instruction`](../reference/glossary#component)
 component — not a raw chat message — with a description, requirements, user variables,
 grounding context, few-shot examples, and images. The instruction is rendered through
-[Jinja2](https://jinja.palletsprojects.com/) templates and run through an [instruct–validate–repair (IVR)](../guide/glossary#ivr-instruct-validate-repair) loop by default.
+[Jinja2](https://jinja.palletsprojects.com/) templates and run through an [instruct–validate–repair (IVR)](../reference/glossary#ivr-instruct-validate-repair) loop by default.
 
 ## Basic `instruct()`
 
@@ -23,7 +23,7 @@ print(str(email))
 # Output will vary — LLM responses depend on model and temperature.
 ```
 
-`instruct()` returns a [`ModelOutputThunk`](../guide/glossary#modeloutputthunk). Access the result as a string with
+`instruct()` returns a [`ModelOutputThunk`](../reference/glossary#modeloutputthunk). Access the result as a string with
 `str(email)` or via `email.value`.
 
 ## User variables
@@ -76,7 +76,7 @@ print(str(email))
 
 ## Custom validation functions
 
-For deterministic checks, attach a `validation_fn` to a [`Requirement`](../guide/glossary#requirement):
+For deterministic checks, attach a `validation_fn` to a [`Requirement`](../reference/glossary#requirement):
 
 ```python
 from mellea import start_session
@@ -129,7 +129,7 @@ print(str(email))
 
 ## Sampling strategies and the IVR loop
 
-By default, `instruct()` uses [`RejectionSamplingStrategy`](../guide/glossary#sampling-strategy)`(loop_budget=2)`: it
+By default, `instruct()` uses [`RejectionSamplingStrategy`](../reference/glossary#sampling-strategy)`(loop_budget=2)`: it
 generates once, validates all requirements, and retries up to two times if any fail.
 
 Configure the loop explicitly with `strategy`:
@@ -160,7 +160,7 @@ else:
     print(str(result.sample_generations[0].value))
 ```
 
-With `return_sampling_results=True`, `instruct()` returns a [`SamplingResult`](../guide/glossary#samplingresult) instead
+With `return_sampling_results=True`, `instruct()` returns a [`SamplingResult`](../reference/glossary#samplingresult) instead
 of a `ModelOutputThunk`. This lets you inspect whether validation passed and access
 all intermediate generations.
 
@@ -242,7 +242,7 @@ print(str(m.ctx.last_output()))
 # Output will vary — LLM responses depend on model and temperature.
 ```
 
-[`ChatContext`](../guide/glossary#context) accumulates turns. `SimpleContext` (the default) discards the previous
+[`ChatContext`](../reference/glossary#context) accumulates turns. `SimpleContext` (the default) discards the previous
 turn on each call.
 
 ## `chat()` vs `instruct()`

docs/docs/concepts/plugins.mdx

@@ -18,9 +18,9 @@ When an event fires during Mellea's execution (e.g., "about to call the LLM" or
 Plugins are organized into six hook categories:
 
 - **Session Lifecycle** — session init, reset, and cleanup (`session_pre_init`, `session_post_init`, `session_reset`, `session_cleanup`)
-- **[Component](../guide/glossary#component) Lifecycle** — before and after component execution (`component_pre_execute`, `component_post_success`, `component_post_error`)
+- **[Component](../reference/glossary#component) Lifecycle** — before and after component execution (`component_pre_execute`, `component_post_success`, `component_post_error`)
 - **Generation Pipeline** — before and after LLM calls (`generation_pre_call`, `generation_post_call`, `generation_error`)
-- **Validation** — before and after [requirement](../guide/glossary#requirement) checks (`validation_pre_check`, `validation_post_check`)
+- **Validation** — before and after [requirement](../reference/glossary#requirement) checks (`validation_pre_check`, `validation_post_check`)
 - **Sampling Pipeline** — sampling loop events (`sampling_loop_start`, `sampling_iteration`, `sampling_repair`, `sampling_loop_end`)
 - **Tool Execution** — before and after tool invocations (`tool_pre_invoke`, `tool_post_invoke`)
 
@@ -246,7 +246,7 @@ unregister(log_generation)
 
 ### Session scope
 
-Pass plugins to [`start_session()`](../guide/glossary#melleasession), fires only within that session.
+Pass plugins to [`start_session()`](../reference/glossary#melleasession), fires only within that session.
 
 ```python
 from mellea import start_session
@@ -1003,4 +1003,4 @@ from mellea.plugins import (
 
 ---
 
-**See also:** [Glossary](../guide/glossary), [Tools and Agents](../how-to/tools-and-agents), [Security and Taint Tracking](../advanced/security-and-taint-tracking), [OpenTelemetry Tracing](../evaluation-and-observability/opentelemetry-tracing)
+**See also:** [Glossary](../reference/glossary), [Tools and Agents](../how-to/tools-and-agents), [Security and Taint Tracking](../advanced/security-and-taint-tracking), [OpenTelemetry Tracing](../evaluation-and-observability/opentelemetry-tracing)