docs: migrate from Mintlify to Docusaurus 3

.gitignore

@@ -457,6 +457,14 @@ pyrightconfig.json
 
 # Generated documentation (built by tooling/docs-autogen/)
 docs/docs/api/
+!docs/docs/api/index.md
 docs/docs/api-reference.mdx
 docs/docs/reference/cli.md
 .venv-docs-autogen/
+
+# Docusaurus build artifacts
+docs/node_modules/
+docs/build/
+docs/.docusaurus/
+docs/sidebars.api.generated.ts
+docs/sidebars.api.generated.json

docs/docs/advanced/_category_.json

@@ -0,0 +1 @@
+{"label": "Advanced", "position": 8}

docs/docs/advanced/custom-components.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/custom-components"
 title: "Building Custom Components"
 description: "Implement the Component Protocol to create reusable, testable generative building blocks."
 # diataxis: how-to

docs/docs/advanced/inference-time-scaling.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/inference-time-scaling"
 title: "Inference-Time Scaling"
 description: "Control how Mellea generates and validates outputs: rejection sampling, SOFAI, budget forcing, and majority voting."
 # diataxis: how-to

docs/docs/advanced/intrinsics.md

@@ -1,13 +1,12 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/intrinsics"
 title: "Intrinsics"
 description: "Adapter-accelerated RAG quality checks using LoRA/aLoRA adapters with Granite models."
 # diataxis: how-to
 ---
 
 **Prerequisites:** `pip install "mellea[hf]"` for LocalHFBackend (GPU or Apple
 Silicon Mac recommended), or `pip install mellea` for OpenAIBackend with a
-[Granite Switch](../guide/glossary#granite-switch) model served via vLLM.
+[Granite Switch](/reference/glossary#granite-switch) model served via vLLM.
 
 Intrinsics are adapter-accelerated operations for RAG quality checks. They use
 LoRA/aLoRA adapters loaded directly into the HuggingFace backend — faster and more

docs/docs/advanced/lora-and-alora-adapters.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/lora-and-alora-adapters"
 title: "LoRA and aLoRA adapters"
 description: "Train lightweight adapters on your own labeled data and use them as requirement validators in Mellea programs."
 # diataxis: how-to

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

@@ -1,8 +1,7 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/mellea-core-internals"
 title: "Mellea Core Internals"
 description: "The three core data structures and abstraction layers underlying every Mellea program."
-sidebarTitle: "Core Internals"
+sidebar_label: "Core Internals"
 # diataxis: explanation
 ---
 

docs/docs/advanced/prefix-caching-and-kv-blocks.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/prefix-caching-and-kv-blocks"
 title: "Prefix Caching and KV Blocks"
 description: "Reuse KV cache state across calls to eliminate redundant prefill work on LocalHFBackend."
 # diataxis: how-to

docs/docs/advanced/template-formatting.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/advanced/template-formatting"
 title: "Template formatting"
 description: "How Mellea's TemplateFormatter converts Python objects into model-ready text using Jinja2 templates."
 # diataxis: explanation

docs/docs/api/index.md

@@ -0,0 +1,20 @@
+---
+title: API Reference
+description: Auto-generated API reference for the Mellea Python library.
+sidebar_label: Overview
+sidebar_position: 0
+---
+
+This section is generated automatically from Python source docstrings.
+
+Run the autogen pipeline to populate it:
+
+```bash
+uv run poe apidocs
+```
+
+Then rebuild the docs:
+
+```bash
+uv run poe docs-build
+```

docs/docs/community/_category_.json

@@ -0,0 +1 @@
+{"label": "Community", "position": 9}

docs/docs/community/building-extensions.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/community/building-extensions"
 title: "Building Extensions"
 description: "Create custom components, backends, sampling strategies, and requirements to extend Mellea."
 # diataxis: how-to

docs/docs/community/code-of-conduct.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/community/code-of-conduct"
 title: "Code of Conduct"
 description: "Standards and enforcement for the Mellea community."
 # diataxis: reference

docs/docs/community/contributing-guide.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/community/contributing-guide"
 title: "Contributing to Mellea"
 description: "Development setup, coding standards, and PR process for Mellea contributors."
 # diataxis: how-to

docs/docs/concepts/_category_.json

@@ -0,0 +1 @@
+{"label": "Concepts", "position": 3}

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

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/architecture-vs-agents"
 title: "Mellea vs Orchestration Frameworks"
 description: "What makes Mellea different from LangChain, smolagents, and other agent frameworks — and how they work together."
 # diataxis: explanation

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

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/context-and-sessions"
 title: "Context and Sessions"
 description: "How Component, Backend, Context, and Session fit together in Mellea's architecture."
 # diataxis: explanation

docs/docs/concepts/generative-functions.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/generative-functions"
 title: "Generative Functions"
 description: "How the @generative decorator turns a Python function signature into an LLM-backed implementation."
 # diataxis: explanation

docs/docs/concepts/generative-programming.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/generative-programming"
 title: "Generative Programming"
 description: "The ideas behind Mellea — what generative programs are, why they're hard, and how Mellea addresses those challenges."
 # diataxis: explanation

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

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/instruct-validate-repair"
 title: "The Instruction Model"
 description: "How instruct(), requirements, and the IVR loop work in Mellea."
 # diataxis: explanation

docs/docs/concepts/mobjects-and-mify.md

@@ -1,11 +1,10 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/mobjects-and-mify"
 title: "MObjects and mify"
 description: "How the @mify decorator turns any Python class into an LLM-queryable object with controlled field and method exposure."
 # diataxis: explanation
 ---
 
-> **Looking to use this in code?** See [Tutorial 05: MIFYing Legacy Code](../tutorials/05-mifying-legacy-code) for a practical walkthrough.
+> **Looking to use this in code?** See [Tutorial 05: MIFYing Legacy Code](../tutorials/mifying-legacy-code) for a practical walkthrough.
 
 Object-oriented programming organizes related data and the methods that operate on it into
 classes. Mellea applies the same principle to LLM interactions: an **MObject** is a Python

docs/docs/concepts/plugins.mdx

@@ -1,8 +1,7 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/plugins"
 title: "Plugins & Hooks"
 description: "Intercept and customize Mellea's execution pipeline with plugins — enforce policies, add observability, and transform payloads at well-defined hook points."
-sidebarTitle: "Plugins & Hooks"
+sidebar_label: "Plugins & Hooks"
 # diataxis: explanation
 ---
 
@@ -25,9 +24,9 @@ Plugins are organized into six hook categories:
 - **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`)
 
-<Note>
+:::note
 Plugins require the hooks extra: `pip install 'mellea[hooks]'`
-</Note>
+:::
 
 ---
 
@@ -675,9 +674,9 @@ async def enforce_tool_allowlist(payload, ctx):
         return block(f"Tool '{payload.model_tool_call.name}' not permitted", code="TOOL_NOT_ALLOWED")
 ```
 
-<Note>
+:::note
 The payload includes an `is_control_flow` field that is `True` for framework control-flow tools (e.g. the ReAct loop's `final_answer`). Allowlist plugins should check this field to avoid blocking internal tools. See [Control-flow tools](#control-flow-tools) for the recommended pattern.
-</Note>
+:::
 
 #### `tool_post_invoke`
 
@@ -720,9 +719,9 @@ This table summarizes which fields are writable for each hook type. Changes to n
 | `tool_pre_invoke` | `model_tool_call` |
 | `tool_post_invoke` | `tool_output` |
 
-<Warning>
+:::warning
 Only `SEQUENTIAL` and `TRANSFORM` modes can modify payloads. `AUDIT`, `CONCURRENT`, and `FIRE_AND_FORGET` modes have their modifications silently discarded regardless of the policy table.
-</Warning>
+:::
 
 ---
 
@@ -788,9 +787,9 @@ async def send_telemetry(payload, ctx):
     await telemetry_client.send({"component": payload.component_type})
 ```
 
-<Note>
+:::note
 The FIRE_AND_FORGET log output may appear after the main result is printed. This is expected behavior, as these hooks run in the background.
-</Note>
+:::
 
 ### Chaining
 

docs/docs/concepts/requirements-system.md

@@ -1,5 +1,4 @@
 ---
-canonical: "https://docs.mellea.ai/concepts/requirements-system"
 title: "The Requirements System"
 description: "How Requirement, ValidationResult, and the IVR loop work together to enforce constraints on generative output."
 # diataxis: explanation