Merge pull request #759 from Pipelex/release/v0.20.9

Release v0.20.9

Author: lchoquel

.claude/skills/release/SKILL.md

@@ -44,7 +44,19 @@ Run `make agent-check`. This is the gate — if it fails, stop and report the
 errors so they can be fixed before retrying. Do not proceed past this step on
 failure.
 
-### 4. Finalize the changelog
+### 4. Ensure we're on the right branch
+
+The release branch must be named `release/vX.Y.Z` where X.Y.Z is the **new**
+version. All file modifications (changelog, version bump, lock, badge) must
+happen on this branch.
+
+- If already on `release/vX.Y.Z` matching the new version, stay on it.
+- If on `dev`, `main`, or any other branch, create and switch to
+  `release/vX.Y.Z` from the current HEAD.
+- If on a `release/` branch for a **different** version, warn the user and ask
+  how to proceed.
+
+### 5. Finalize the changelog
 
 Add a new version entry at the top of the changelog for the release.
 
@@ -71,18 +83,18 @@ Add a new version entry at the top of the changelog for the release.
 ...
 ```
 
-### 5. Bump the version in pyproject.toml
+### 6. Bump the version in pyproject.toml
 
 Edit `pyproject.toml` line 3 to the new version string. Only change the version
 field — don't touch anything else.
 
-### 6. Lock dependencies
+### 7. Lock dependencies
 
 Run `make li` to regenerate `uv.lock` and reinstall. This ensures the lockfile
 reflects the new version in `pyproject.toml`. If this step fails, stop and
 report the error.
 
-### 7. Update the test count badge
+### 8. Update the test count badge
 
 Run `make test-count` to get the current number of tests. Then update
 `.badges/tests.json` — set the `"message"` field to the count returned by
@@ -91,17 +103,6 @@ Run `make test-count` to get the current number of tests. Then update
 After updating, run `make check-test-badge` to verify the badge matches. If it
 fails, re-check the count and fix the badge file.
 
-### 8. Ensure we're on the right branch
-
-The release branch must be named `release/vX.Y.Z` where X.Y.Z is the **new**
-version.
-
-- If already on `release/vX.Y.Z` matching the new version, stay on it.
-- If on `dev`, `main`, or any other branch, create and switch to
-  `release/vX.Y.Z` from the current HEAD.
-- If on a `release/` branch for a **different** version, warn the user and ask
-  how to proceed.
-
 ### 9. Commit and push
 
 Stage all release-related changes. This includes at minimum `pyproject.toml`,

.github/workflows/doc-check.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Install mkdocs
         run: |
           python -m pip install --upgrade pip
-          pip install mkdocs==1.6.1 mkdocs-material==9.6.14 mkdocs-glightbox==0.4.0 mkdocs-meta-manager==1.1.0
+          pip install mkdocs==1.6.1 mkdocs-material==9.6.14 mkdocs-glightbox==0.4.0 mkdocs-meta-manager==1.1.0 mkdocs-redirects==1.2.2
 
       - name: Check documentation build
         run: mkdocs build --strict

.gitignore

@@ -73,4 +73,5 @@ mthds-wip
 derived/
 
 # Claude plans
-.claude/plans/
+.claude/plans/
+.gstack/

.pipelex/inference/backends/pipelex_gateway.toml

@@ -30,7 +30,7 @@
 # with direct provider backends (openai, anthropic, etc.) instead.
 #
 # Documentation:
-# https://docs.pipelex.com/home/7-configuration/config-technical/inference-backend-config/
+# https://docs.pipelex.com/latest/configuration/config-technical/inference-backend-config/
 # Support: https://go.pipelex.com/discord
 #
 ################################################################################

.pipelex/inference/backends/pipelex_gateway_models.md

@@ -1,6 +1,6 @@
 # Pipelex Gateway — Available Models
 This file lists the LLMs, document extraction models, and image generation models currently available through Pipelex Gateway.
-For configuration details, see the [documentation](https://docs.pipelex.com/latest/home/5-setup/configure-ai-providers/#option-1-pipelex-gateway-easiest-for-getting-started).
+For configuration details, see the [documentation](https://docs.pipelex.com/latest/setup/configure-ai-providers/#option-1-pipelex-gateway-easiest-and-most-powerful-for-getting-started).
 
 ## Language Models (LLM)
 
@@ -515,6 +515,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
 
 
 > **AUTO-GENERATED FILE** - Do not edit manually.
-> Last updated: 2026-03-10T06:49:52Z
+> Last updated: 2026-03-14T15:45:06Z
 >
 > Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.

.pipelex/inference/backends/pipelex_gateway_models_plain.md

@@ -1,7 +1,7 @@
 # Pipelex Gateway — Available Models (Plain Text)
 
 This file lists the LLMs, document extraction models, and image generation models currently available through Pipelex Gateway.
-For configuration details, see the [documentation](https://docs.pipelex.com/latest/home/5-setup/configure-ai-providers/#option-1-pipelex-gateway-easiest-for-getting-started).
+For configuration details, see the [documentation](https://docs.pipelex.com/latest/setup/configure-ai-providers/#option-1-pipelex-gateway-easiest-and-most-powerful-for-getting-started).
 
 **Note:** This is the plain-text readable version. See `pipelex_gateway_models.md` for the HTML-styled version.
 
@@ -193,6 +193,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late
 
 
 > **AUTO-GENERATED FILE** - Do not edit manually.
-> Last updated: 2026-03-10T06:49:52Z
+> Last updated: 2026-03-14T15:45:06Z
 >
 > Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [v0.20.9] - 2026-03-16
+
+### Changed
+
+- Reorganize documentation site architecture and navigation.
+- Add SEO meta descriptions to all doc pages.
+- Redesign README: lead with value, collapse details.
+
 ## [v0.20.8] - 2026-03-13
 
 - Add `needs_model_specs=True` to agent CLI run and models commands.
@@ -186,7 +194,7 @@
 
     **`pipelex build runner`** — Now automatically generates both the Python runner file AND the required Pydantic structures. When you run this command, it creates a complete, ready-to-execute Python script that imports the generated structures, so you can immediately use typed objects in your pipeline code.
 
-    See the [Build Commands documentation](https://docs.pipelex.com/home/9-tools/cli/#build-commands) for usage examples.
+    See the [Build Commands documentation](https://docs.pipelex.com/latest/tools/cli/build/) for usage examples.
 
 - **New Backends & Models**:
     - **Hugging Face Inference** — Support for Hugging Face Inference API, including `qwen-image` text-to-image model.
@@ -209,7 +217,7 @@
 - **LLM Reasoning Controls**: Unified support for "Thinking" models (Chain of Thought) with `reasoning_effort`, `reasoning_budget`, and `thinking_mode` parameters. Supports Anthropic Extended Thinking, Google Gemini Thinking, OpenAI Reasoning (`o1`/`o3`), and Mistral/Magistral models. Includes new presets: `$deep-analysis` and `$quick-reasoning`.
 - **Image-to-Image Generation**: `PipeImgGen` now supports input images via `input_images` field, with `InputImagesTaxonomy` for provider-specific handling and variable reference detection (`{{ var }}`, `$var`, `@var`) in prompts.
 - **PipeCompose "Construct" Mode**: New `construct` mode for building structured objects (dictionaries/Pydantic models) directly from variables.
-- **Nested concepts in inline structures**: You can now define nested structures for your concepts in your `.plx` files. Learn more here: [Nested Concepts in Inline Structures](https://docs.pipelex.com/home/6-build-reliable-ai-workflows/concepts/inline-structures).
+- **Nested concepts in inline structures**: You can now define nested structures for your concepts in your `.plx` files. Learn more here: [Nested Concepts in Inline Structures](https://docs.pipelex.com/latest/building-methods/concepts/inline-structures).
 
 ### Breaking Changes
 
@@ -456,7 +464,7 @@
  - **LLM Reasoning Controls**: Unified support for "Thinking" models (Chain of Thought) with `reasoning_effort`, `reasoning_budget`, and `thinking_mode` parameters. Supports Anthropic Extended Thinking, Google Gemini Thinking, OpenAI Reasoning (`o1`/`o3`), and Mistral/Magistral models. Includes new presets: `$deep-analysis` and `$quick-reasoning`.
  - **Image-to-Image Generation**: `PipeImgGen` now supports input images via `input_images` field, with `InputImagesTaxonomy` for provider-specific handling and variable reference detection (`{{ var }}`, `$var`, `@var`) in prompts.
  - **PipeCompose "Construct" Mode**: New `construct` mode for building structured objects (dictionaries/Pydantic models) directly from variables.
- - **Nested concepts in inline structures**: You can now define nested structures for your concepts in your `.plx` files. Learn more here: [Nested Concepts in Inline Structures](https://docs.pipelex.com/home/6-build-reliable-ai-workflows/concepts/inline-structures).
+ - **Nested concepts in inline structures**: You can now define nested structures for your concepts in your `.plx` files. Learn more here: [Nested Concepts in Inline Structures](https://docs.pipelex.com/latest/building-methods/concepts/inline-structures).
 
 ### Added
  - **Builder Auto-Repair**: Self-healing capabilities including auto-generation of undeclared concepts, multiplicity mismatch fixes, and pruning of unreachable pipes/unused concepts.
@@ -558,7 +566,7 @@
 
     **`pipelex build runner`** — Now automatically generates both the Python runner file AND the required Pydantic structures. When you run this command, it creates a complete, ready-to-execute Python script that imports the generated structures, so you can immediately use typed objects in your pipeline code.
 
-    See the [Build Commands documentation](https://docs.pipelex.com/home/9-tools/cli/#build-commands) for usage examples.
+    See the [Build Commands documentation](https://docs.pipelex.com/latest/tools/cli/build/) for usage examples.
 
 - **New Backends & Models**:
     - **Hugging Face Inference** — Support for Hugging Face Inference API, including `qwen-image` text-to-image model.
@@ -1237,13 +1245,13 @@ This is all in the spirit of making Pipelex a declarative language, where you ex
 
 We've completely redesigned how LLMs are configured and accessed in Pipelex, making it more flexible and easier to get started:
 
-- **Get started in seconds** with [Pipelex Inference](home/7-configuration/config-technical/inference-backend-config.md): Use a single API key to access all major LLM providers (OpenAI, Anthropic, Google, Mistral, and more)
+- **Get started in seconds** with [Pipelex Inference](configuration/config-technical/inference-backend-config.md): Use a single API key to access all major LLM providers (OpenAI, Anthropic, Google, Mistral, and more)
 - **Flexible backend configuration**: Configure multiple inference backends (Azure OpenAI, Amazon Bedrock, Vertex AI, etc.) through simple TOML files in `.pipelex/inference/`
-- **Smart model routing**: Automatically route models to the right backend using [routing profiles](home/7-configuration/config-technical/inference-backend-config.md#routing-profiles) with pattern matching
+- **Smart model routing**: Automatically route models to the right backend using [routing profiles](configuration/config-technical/inference-backend-config.md#routing-profiles) with pattern matching
 - **User-friendly aliases**: Define shortcuts like `best-claude` → `claude-4.1-opus` with optional fallback chains
 - **Cost-aware model specs**: Each model includes detailed pricing, capabilities, and constraints for better cost management
 
-For complete details, see the [Inference Backend Configuration](home/7-configuration/config-technical/inference-backend-config.md) documentation.
+For complete details, see the [Inference Backend Configuration](configuration/config-technical/inference-backend-config.md) documentation.
 
 ### Added
 

CLAUDE.md

@@ -259,6 +259,13 @@ This document outlines the core coding standards, best practices, and quality co
 
 ## Standards related to developing the Pipelex codebase
 
+### Spec vs Blueprint Architecture
+
+- **Blueprints** (`pipelex/pipe_operators/`, `pipelex/pipe_controllers/`, `pipelex/core/`) are the MTHDS language reference — what `.mthds` files parse into.
+- **Specs** (`pipelex/builder/pipe/`) are a convenience authoring format for AI agents. Each spec has `to_blueprint()` that transforms it into the corresponding blueprint. Spec-level fields may differ from blueprint-level fields.
+
+When adding validation or fields, decide which layer they belong to. Language rules go on blueprints; authoring convenience goes on specs. See `pipelex/builder/CLAUDE.md` for details.
+
 ### Main config
 
 - The main config model is defined using `ConfigModel` classes, derived from `pydantic BaseModel`

Makefile

@@ -802,6 +802,9 @@ check-TODOs: env
 DOCS_VERSION := $(shell grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
 SITE_DOMAIN := $(shell cat docs/CNAME 2>/dev/null | tr -d '[:space:]')
 
+# Authoritative robots.txt for the domain root (docs.pipelex.com/robots.txt).
+# Deployed by docs-deploy-root. Note: docs/robots.txt is a no-op — it only
+# lands at /latest/robots.txt, which crawlers ignore per RFC 9309.
 define ROOT_ROBOTS_TXT
 User-agent: *
 Allow: /latest/
@@ -818,9 +821,22 @@ define ROOT_INDEX_HTML
     <title>Redirecting to latest documentation...</title>
     <meta http-equiv="refresh" content="0;url=/latest/">
     <link rel="canonical" href="https://$(SITE_DOMAIN)/latest/">
+    <style>
+        body {
+            margin: 0;
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            background: #2e303e;
+            color: #ccc;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+        }
+        a { color: #45BF9F; text-decoration: none; }
+    </style>
 </head>
 <body>
-    <p>Redirecting to <a href="/latest/">latest documentation</a>...</p>
+    <p>Redirecting to <a href="/latest/">latest documentation</a>&#8230;</p>
 </body>
 </html>
 endef