docs: consolidate how-to section

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

@@ -277,5 +277,5 @@ for a worked example.
 
 **See also:**
 [Generative Programming](../concepts/generative-programming) |
-[Working with Data](../guide/working-with-data) |
+[Working with Data](../how-to/working-with-data) |
 [Async and Streaming](../how-to/use-async-and-streaming)

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

@@ -133,13 +133,13 @@ orchestrator:
 
 - **ReACT loops** — implement thought/action/observation cycles using `m.chat()`
   with [`ChatContext`](../guide/glossary#chatcontext) and the `@tool` decorator. See
-  [Tools and Agents](../guide/tools-and-agents).
+  [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).
 - **Structured outputs** — use `@generative` with Pydantic models or `Literal` types
   to enforce type-safe structured output at each step. See
-  [Generative Functions](../guide/generative-functions).
+  [Generative Functions](../how-to/generative-functions).
 
 For programs where the control flow is fixed in Python — a pipeline, an extraction
 workflow, a classification step — there is no need for a separate orchestrator.
@@ -211,5 +211,5 @@ tools or steps.
 
 ---
 
-**See also:** [Tools and Agents](../guide/tools-and-agents) |
+**See also:** [Tools and Agents](../how-to/tools-and-agents) |
 [Security and Taint Tracking](../advanced/security-and-taint-tracking)

docs/docs/concepts/generative-functions.md

@@ -9,7 +9,7 @@ In a generative program, a function can have the same interface but delegate its
 to an LLM. Mellea calls these [**generative functions**](../guide/glossary#generative-function) and provides the [`@generative`](../guide/glossary#generative) decorator
 to define them.
 
-> **Looking to use this in code?** See [Generative Functions](../guide/generative-functions) for practical examples and API details.
+> **Looking to use this in code?** See [Generative Functions](../how-to/generative-functions) for practical examples and API details.
 
 ## The @generative decorator
 
@@ -167,4 +167,4 @@ Use `@generative` when you want a named, typed, reusable LLM-backed operation. U
 
 **See also:** [Instruct, Validate, Repair](./instruct-validate-repair) |
 [The Requirements System](./requirements-system) |
-[Tools and Agents](../guide/tools-and-agents)
+[Tools and Agents](../how-to/tools-and-agents)

docs/docs/concepts/generative-programming.md

@@ -143,4 +143,4 @@ These principles recur throughout Mellea:
 **See also:**
 [Instruct, Validate, Repair](./instruct-validate-repair) |
 [Inference-Time Scaling](../advanced/inference-time-scaling) |
-[Working with Data](../guide/working-with-data)
+[Working with Data](../how-to/working-with-data)

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

@@ -188,7 +188,7 @@ print(str(answer))
 `grounding_context` maps string keys to document text. The keys are arbitrary
 labels — they appear in the prompt as `[key] = value` so the model can reference
 them by name, but there is no required naming convention (e.g. `"doc0"`, `"annual_report"`,
-`"spec"` all work). See [Working with Data](../guide/working-with-data) for richer
+`"spec"` all work). See [Working with Data](../how-to/working-with-data) for richer
 document handling using MObjects and `RichDocument`.
 
 ## ICL examples

docs/docs/concepts/plugins.mdx

@@ -989,4 +989,4 @@ from mellea.plugins import (
 
 ---
 
-**See also:** [Glossary](../guide/glossary), [Tools and Agents](../guide/tools-and-agents), [Security and Taint Tracking](../advanced/security-and-taint-tracking), [OpenTelemetry Tracing](../evaluation-and-observability/opentelemetry-tracing)
+**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)

docs/docs/docs.json

@@ -54,12 +54,12 @@
           {
             "group": "How-To",
             "pages": [
-              "guide/generative-functions",
-              "guide/tools-and-agents",
-              "guide/working-with-data",
-              "guide/backends-and-configuration",
-              "guide/act-and-aact",
-              "guide/m-decompose",
+              "how-to/generative-functions",
+              "how-to/tools-and-agents",
+              "how-to/working-with-data",
+              "how-to/backends-and-configuration",
+              "how-to/act-and-aact",
+              "how-to/m-decompose",
               "how-to/use-async-and-streaming",
               "how-to/use-context-and-sessions",
               "how-to/enforce-structured-output",
@@ -443,7 +443,7 @@
     },
     {
       "source": "/overview/architecture",
-      "destination": "/guide/backends-and-configuration"
+      "destination": "/how-to/backends-and-configuration"
     },
     {
       "source": "/core-concept/instruct-validate-repair",
@@ -455,15 +455,15 @@
     },
     {
       "source": "/core-concept/generative-slots",
-      "destination": "/guide/generative-functions"
+      "destination": "/how-to/generative-functions"
     },
     {
       "source": "/core-concept/mobjects",
       "destination": "/concepts/mobjects-and-mify"
     },
     {
       "source": "/core-concept/agents",
-      "destination": "/guide/tools-and-agents"
+      "destination": "/how-to/tools-and-agents"
     },
     {
       "source": "/core-concept/context-management",
@@ -491,7 +491,7 @@
     },
     {
       "source": "/core-concept/adapters",
-      "destination": "/guide/tools-and-agents"
+      "destination": "/how-to/tools-and-agents"
     },
     {
       "source": "/core-concept/contribution-guide",
@@ -547,7 +547,7 @@
     },
     {
       "source": "/dev/tool-calling",
-      "destination": "/guide/tools-and-agents"
+      "destination": "/how-to/tools-and-agents"
     },
     {
       "source": "/api/cli/m",
@@ -616,6 +616,30 @@
     {
       "source": "/api/cli/fix/genstub_fixer",
       "destination": "/reference/cli"
+    },
+    {
+      "source": "/guide/generative-functions",
+      "destination": "/how-to/generative-functions"
+    },
+    {
+      "source": "/guide/tools-and-agents",
+      "destination": "/how-to/tools-and-agents"
+    },
+    {
+      "source": "/guide/working-with-data",
+      "destination": "/how-to/working-with-data"
+    },
+    {
+      "source": "/guide/backends-and-configuration",
+      "destination": "/how-to/backends-and-configuration"
+    },
+    {
+      "source": "/guide/act-and-aact",
+      "destination": "/how-to/act-and-aact"
+    },
+    {
+      "source": "/guide/m-decompose",
+      "destination": "/how-to/m-decompose"
     }
   ]
 }

docs/docs/examples/data-extraction-pipeline.md

@@ -35,7 +35,7 @@ m = start_session()
 
 `start_session()` with no arguments creates a session backed by the default
 local model. The `model_ids` import is available if you want to switch to a
-specific model later (see [Backends and configuration](../guide/backends-and-configuration)).
+specific model later (see [Backends and configuration](../how-to/backends-and-configuration)).
 
 ### Declaring the extraction function
 

docs/docs/getting-started/quickstart.md

@@ -94,7 +94,7 @@ chat.
 
 **Backends** — Pluggable model providers. Ollama is the default. OpenAI, [LiteLLM](../guide/glossary#litellm--litellmbackend),
 HuggingFace, and WatsonX are also supported. See
-[Backends and Configuration](../guide/backends-and-configuration).
+[Backends and Configuration](../how-to/backends-and-configuration).
 
 ## Troubleshooting
 

docs/docs/guide/CONTRIBUTING.md

@@ -74,7 +74,7 @@ before the first H2, so readers can orient themselves quickly:
 - On the **explanation** page:
 
   ```markdown
-  > **Looking to use this in code?** See [Generative Functions](../guide/generative-functions) for practical examples and API details.
+  > **Looking to use this in code?** See [Generative Functions](../how-to/generative-functions) for practical examples and API details.
   ```
 
 - On the **how-to** page:

docs/docs/how-to/enforce-structured-output.md

@@ -260,5 +260,5 @@ Both patterns support the full IVR loop, requirements, sampling strategies, and
 
 ---
 
-**See also:** [Generative Functions](../guide/generative-functions) |
+**See also:** [Generative Functions](../how-to/generative-functions) |
 [The Requirements System](../concepts/requirements-system)

docs/docs/guide/m-decompose.md → docs/docs/how-to/m-decompose.md

@@ -123,4 +123,4 @@ For tasks that fit comfortably in a single prompt, use `m.instruct()` directly.
 
 ---
 
-**See also:** [Tools and Agents](../guide/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [CLI Reference](../reference/cli)
+**See also:** [Tools and Agents](../how-to/tools-and-agents) | [Refactor Prompts with CLI](../how-to/refactor-prompts-with-cli) | [CLI Reference](../reference/cli)

docs/docs/how-to/use-async-and-streaming.md

@@ -166,4 +166,4 @@ For parallel generation, use `SimpleContext`.
 
 ---
 
-**See also:** [Tutorial 02: Streaming and Async](../tutorials/02-streaming-and-async) | [act() and aact()](../guide/act-and-aact)
+**See also:** [Tutorial 02: Streaming and Async](../tutorials/02-streaming-and-async) | [act() and aact()](../how-to/act-and-aact)

docs/docs/how-to/use-images-and-vision.md

@@ -121,5 +121,5 @@ To remove images from context on the next turn, pass `images=[]` explicitly.
 
 ---
 
-**See also:** [Working with Data](../guide/working-with-data) |
+**See also:** [Working with Data](../how-to/working-with-data) |
 [The Instruction Model](../concepts/instruct-validate-repair)

docs/docs/guide/working-with-data.md → docs/docs/how-to/working-with-data.md

@@ -250,4 +250,4 @@ tools during `transform()` calls automatically.
 
 ---
 
-**See also:** [act() and aact()](../guide/act-and-aact) | [MObjects and mify](../concepts/mobjects-and-mify)
+**See also:** [act() and aact()](../how-to/act-and-aact) | [MObjects and mify](../concepts/mobjects-and-mify)

docs/docs/index.mdx

@@ -72,7 +72,7 @@ Mellea's design rests on three interlocking ideas.
   <Card title="Inference-time scaling" icon="chart-line" href="/advanced/inference-time-scaling">
     Best-of-n, SOFAI, majority voting — swap strategies in one line.
   </Card>
-  <Card title="Tools and agents" icon="wrench" href="/guide/tools-and-agents">
+  <Card title="Tools and agents" icon="wrench" href="/how-to/tools-and-agents">
     `@tool`, `MelleaTool`, and the ReACT loop for goal-driven multi-step agents.
   </Card>
 </CardGroup>
@@ -105,7 +105,7 @@ Mellea is backend-agnostic. The same program runs on any inference engine.
   </Card>
 </CardGroup>
 
-See [Backends and configuration](/guide/backends-and-configuration) for the full list of supported backends and how to configure them.
+See [Backends and configuration](/how-to/backends-and-configuration) for the full list of supported backends and how to configure them.
 
 ## How-to guides
 

docs/docs/integrations/bedrock.md

@@ -145,4 +145,4 @@ so vision-capable models (e.g., `amazon.nova-pro-v1:0`) support image input via
 
 ---
 
-**See also:** [Backends and Configuration](../guide/backends-and-configuration)
+**See also:** [Backends and Configuration](../how-to/backends-and-configuration)

docs/docs/integrations/huggingface.md

@@ -115,5 +115,5 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 
 ---
 
-**See also:** [Backends and Configuration](../guide/backends-and-configuration) |
+**See also:** [Backends and Configuration](../how-to/backends-and-configuration) |
 [LoRA and aLoRA Adapters](../advanced/lora-and-alora-adapters)

docs/docs/integrations/langchain.md

@@ -105,11 +105,11 @@ OpenAI chat format — LlamaIndex, Haystack, Semantic Kernel — works with the
 | -------- | --- |
 | Your tool exists as a LangChain `BaseTool` | `MelleaTool.from_langchain(tool)` |
 | Your tool exists as a smolagents `Tool` | [`MelleaTool.from_smolagents(tool)`](./smolagents) |
-| You have a plain Python function to expose | [`@tool` decorator](../guide/tools-and-agents) |
+| You have a plain Python function to expose | [`@tool` decorator](../how-to/tools-and-agents) |
 | You have LangChain message history to continue | `convert_to_openai_messages` → `ChatContext` |
 | You want Mellea as an OpenAI endpoint for another framework | [`m serve`](./m-serve) |
 
 ---
 
-**See also:** [Tools and Agents](../guide/tools-and-agents) |
+**See also:** [Tools and Agents](../how-to/tools-and-agents) |
 [Context and Sessions](../concepts/context-and-sessions)

docs/docs/integrations/m-serve.md

@@ -112,5 +112,5 @@ print(response.choices[0].message.content)
 ---
 
 **See also:** [Context and Sessions](../concepts/context-and-sessions) |
-[Backends and Configuration](../guide/backends-and-configuration) |
+[Backends and Configuration](../how-to/backends-and-configuration) |
 [CLI Reference](../reference/cli)

docs/docs/integrations/mcp.md

@@ -115,4 +115,4 @@ uv run your_server.py
 
 ---
 
-**See also:** [Backends and Configuration](../guide/backends-and-configuration)
+**See also:** [Backends and Configuration](../how-to/backends-and-configuration)

docs/docs/integrations/ollama.md

@@ -205,7 +205,7 @@ m = MelleaSession(
 )
 ```
 
-See [Backends and Configuration](../guide/backends-and-configuration) for the
+See [Backends and Configuration](../how-to/backends-and-configuration) for the
 full `OpenAIBackend` reference.
 
 ## Troubleshooting
@@ -240,5 +240,5 @@ pip install mellea
 
 ---
 
-**See also:** [Backends and Configuration](../guide/backends-and-configuration) |
+**See also:** [Backends and Configuration](../how-to/backends-and-configuration) |
 [Getting Started](../getting-started/installation)

docs/docs/integrations/openai.md

@@ -234,7 +234,7 @@ m = MelleaSession(
 > **Note (review needed):** Direct Anthropic API compatibility via this path has not
 > been verified against the current Mellea version. If you are using Anthropic,
 > LiteLLM provides a verified integration — see
-> [Backends and Configuration](../guide/backends-and-configuration).
+> [Backends and Configuration](../how-to/backends-and-configuration).
 
 ## Troubleshooting
 
@@ -256,5 +256,5 @@ local servers, list available models from the server's API or UI.
 
 ---
 
-**See also:** [Backends and Configuration](../guide/backends-and-configuration) |
+**See also:** [Backends and Configuration](../how-to/backends-and-configuration) |
 [Enforce Structured Output](../how-to/enforce-structured-output)

docs/docs/integrations/smolagents.md

@@ -55,11 +55,11 @@ description and parameter types are preserved exactly.
 | -------- | --- |
 | Your tool exists as a LangChain `BaseTool` | [`MelleaTool.from_langchain(tool)`](./langchain) |
 | Your tool exists as a smolagents `Tool` | `MelleaTool.from_smolagents(tool)` |
-| You have a plain Python function to expose | [`@tool` decorator](../guide/tools-and-agents) |
+| You have a plain Python function to expose | [`@tool` decorator](../how-to/tools-and-agents) |
 | You have LangChain message history to continue | [`convert_to_openai_messages` → `ChatContext`](./langchain.md#seeding-a-session-with-langchain-message-history) |
 | You want Mellea as an OpenAI endpoint for another framework | [`m serve`](./m-serve) |
 
 ---
 
-**See also:** [Tools and Agents](../guide/tools-and-agents) |
+**See also:** [Tools and Agents](../how-to/tools-and-agents) |
 [Context and Sessions](../concepts/context-and-sessions)

docs/docs/integrations/vertex-ai.md

@@ -244,4 +244,4 @@ pip install google-cloud-aiplatform
 ---
 
 **See also:** [OpenAI and OpenAI-Compatible APIs](../integrations/openai) |
-[Backends and Configuration](../guide/backends-and-configuration)
+[Backends and Configuration](../how-to/backends-and-configuration)

docs/docs/integrations/watsonx.md

@@ -5,8 +5,8 @@ description: "Run Mellea with IBM WatsonX AI using the WatsonxAIBackend."
 ---
 
 > **Deprecated:** The native WatsonX backend is deprecated since v0.4. Use the
-> [LiteLLM](../guide/backends-and-configuration#litellm-backend) or
-> [OpenAI](../guide/backends-and-configuration#openai-backend) backend with a
+> [LiteLLM](../how-to/backends-and-configuration#litellm-backend) or
+> [OpenAI](../how-to/backends-and-configuration#openai-backend) backend with a
 > WatsonX-compatible endpoint instead.
 
 The WatsonX backend connects to IBM's managed AI platform. It requires an API key,
@@ -111,4 +111,4 @@ pip install 'mellea[watsonx]'
 
 ---
 
-**See also:** [Backends and Configuration](../guide/backends-and-configuration)
+**See also:** [Backends and Configuration](../how-to/backends-and-configuration)

docs/docs/tutorials/03-using-generative-stubs.md

@@ -258,4 +258,4 @@ context-steerable generative functions:
 
 ---
 
-**See also:** [Generative Functions](../guide/generative-functions) | [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers)
+**See also:** [Generative Functions](../how-to/generative-functions) | [The Requirements System](../concepts/requirements-system) | [Write Custom Verifiers](../how-to/write-custom-verifiers)

docs/docs/tutorials/04-making-agents-reliable.md

@@ -489,4 +489,4 @@ agentic system:
 
 ---
 
-**See also:** [The Requirements System](../concepts/requirements-system) | [Security and Taint Tracking](../advanced/security-and-taint-tracking) | [Tools and Agents](../guide/tools-and-agents)
+**See also:** [The Requirements System](../concepts/requirements-system) | [Security and Taint Tracking](../advanced/security-and-taint-tracking) | [Tools and Agents](../how-to/tools-and-agents)

docs/docs/tutorials/05-mifying-legacy-code.md

@@ -194,5 +194,5 @@ modifying their class definitions:
 | `mify(obj)` | You don't own the class |
 
 **See also:** [MObjects and mify](../concepts/mobjects-and-mify) |
-[Working with Data](../guide/working-with-data) |
+[Working with Data](../how-to/working-with-data) |
 [Tutorial 03: Using Generative Stubs](./03-using-generative-stubs)