docs: add missing example categories to examples catalogue (#645) (#672)

* docs: add missing example categories to examples catalogue (#645)

Add plugins, m_decompose, tutorial, notebooks, and hello_world to the
examples index page so all runnable example directories are discoverable
from the published docs.

Also add a note to CONTRIBUTING.md reminding authors to update the
catalogue when adding new example directories.

* docs: add examples catalogue validation check to doc validator

Add validate_examples_catalogue() to validate.py that checks every
example directory under docs/examples/ (containing .py files) has a
corresponding entry in docs/docs/examples/index.md.

Also refine the CONTRIBUTING.md guideline to frame it as a check
rather than only an instruction for when adding examples.

Author: planetf1

docs/docs/examples/index.md

@@ -49,6 +49,12 @@ to run.
 | `tools/` | `@tool` definition, code interpreter integration, tool argument validation, safe `eval` patterns |
 | `mini_researcher/` | Complete research assistant: multi-model architecture, document retrieval, safety checks, custom validation pipeline |
 
+### Extensibility
+
+| Category | What it shows |
+| -------- | ------------- |
+| `plugins/` | Plugin system end-to-end: function hooks, class-based plugins, payload modification, scoped and session-scoped plugins, `PluginSet` composition, execution modes, tool hooks, and testing patterns |
+
 ### Safety and validation
 
 | Category | What it shows |
@@ -60,6 +66,7 @@ to run.
 | Category | What it shows |
 | -------- | ------------- |
 | `m_serve/` | Deploying Mellea programs as REST APIs with production deployment patterns |
+| `m_decompose/` | Decomposing complex prompts into sub-tasks via the CLI and Python API |
 | `library_interop/` | LangChain message conversion, OpenAI format compatibility, cross-library workflows |
 | `mcp/` | MCP tool creation, Claude Desktop integration, Langflow integration |
 | `bedrock/` | Amazon Bedrock backend configuration and usage |
@@ -90,6 +97,14 @@ to run.
 | -------- | ------------- |
 | `melp/` | ⚠️ Experimental lazy evaluation — thunks, deferred execution, advanced control flow |
 
+### Getting started and tutorials
+
+| Category | What it shows |
+| -------- | ------------- |
+| `hello_world.py` | Minimal single-file starting point |
+| `tutorial/` | Python script versions of the tutorials: email generation, IVR, generative slots, contexts, MObjects, model options, and more |
+| `notebooks/` | Jupyter notebook versions of the same tutorials for interactive, cell-by-cell exploration |
+
 ---
 
 ## Running the examples

docs/docs/guide/CONTRIBUTING.md

@@ -251,6 +251,15 @@ Where a CI-tested example exists in `docs/examples/`, link it:
 
 Only link examples that are current and in CI.
 
+### Keeping the examples catalogue up to date
+
+Check that every example directory under `docs/examples/` has a corresponding
+row in the catalogue table in `docs/docs/examples/index.md`. When adding a new
+example directory, add a row with a short description of what the examples
+demonstrate. This ensures users browsing the published docs can discover all
+available examples, not only the ones linked from individual guide or concept
+pages.
+
 ---
 
 ## Missing content

tooling/docs-autogen/test_validate.py

@@ -8,6 +8,7 @@
 from validate import (
     generate_report,
     validate_doc_imports,
+    validate_examples_catalogue,
     validate_internal_links,
     validate_mdx_syntax,
     validate_source_links,
@@ -263,5 +264,85 @@ def test_generate_report_all_pass():
     assert report["overall_passed"] is True
 
 
+def test_validate_examples_catalogue_pass():
+    """Test examples catalogue check passes when all dirs are listed."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        docs_root = Path(tmpdir)
+        examples_dir = docs_root / "examples"
+        examples_dir.mkdir()
+        index_dir = docs_root / "docs" / "examples"
+        index_dir.mkdir(parents=True)
+
+        # Create an example directory with a .py file
+        (examples_dir / "my_example").mkdir()
+        (examples_dir / "my_example" / "demo.py").write_text("# demo")
+
+        # Create index listing it
+        (index_dir / "index.md").write_text("| `my_example/` | A demo example |")
+
+        error_count, errors = validate_examples_catalogue(docs_root)
+        assert error_count == 0
+        assert len(errors) == 0
+
+
+def test_validate_examples_catalogue_missing():
+    """Test examples catalogue check catches unlisted directories."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        docs_root = Path(tmpdir)
+        examples_dir = docs_root / "examples"
+        examples_dir.mkdir()
+        index_dir = docs_root / "docs" / "examples"
+        index_dir.mkdir(parents=True)
+
+        # Create an example directory with a .py file
+        (examples_dir / "unlisted_example").mkdir()
+        (examples_dir / "unlisted_example" / "demo.py").write_text("# demo")
+
+        # Create index that does NOT mention it
+        (index_dir / "index.md").write_text("| `other/` | Something else |")
+
+        error_count, errors = validate_examples_catalogue(docs_root)
+        assert error_count == 1
+        assert "unlisted_example" in errors[0]
+
+
+def test_validate_examples_catalogue_skips_helper():
+    """Test examples catalogue check skips the helper directory."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        docs_root = Path(tmpdir)
+        examples_dir = docs_root / "examples"
+        examples_dir.mkdir()
+        index_dir = docs_root / "docs" / "examples"
+        index_dir.mkdir(parents=True)
+
+        # Create helper directory (should be skipped)
+        (examples_dir / "helper").mkdir()
+        (examples_dir / "helper" / "utils.py").write_text("# utils")
+
+        (index_dir / "index.md").write_text("# Examples")
+
+        error_count, _errors = validate_examples_catalogue(docs_root)
+        assert error_count == 0
+
+
+def test_validate_examples_catalogue_skips_empty_dirs():
+    """Test examples catalogue check skips directories with no .py files."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        docs_root = Path(tmpdir)
+        examples_dir = docs_root / "examples"
+        examples_dir.mkdir()
+        index_dir = docs_root / "docs" / "examples"
+        index_dir.mkdir(parents=True)
+
+        # Create directory with only non-Python files
+        (examples_dir / "data_only").mkdir()
+        (examples_dir / "data_only" / "data.json").write_text("{}")
+
+        (index_dir / "index.md").write_text("# Examples")
+
+        error_count, _errors = validate_examples_catalogue(docs_root)
+        assert error_count == 0
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

tooling/docs-autogen/validate.py

@@ -323,6 +323,55 @@ def validate_stale_files(docs_root: Path) -> tuple[int, list[str]]:
     return len(errors), errors
 
 
+def validate_examples_catalogue(docs_root: Path) -> tuple[int, list[str]]:
+    """Check that every example directory is listed in the examples index page.
+
+    Scans ``docs/examples/`` for subdirectories that contain at least one
+    ``.py`` file and verifies each directory name appears in the catalogue
+    table in ``docs/docs/examples/index.md``.
+
+    Args:
+        docs_root: The ``docs/`` directory (parent of ``docs/docs/``).
+
+    Returns:
+        Tuple of (error_count, error_messages).
+    """
+    errors: list[str] = []
+    examples_dir = docs_root / "examples"
+    index_file = docs_root / "docs" / "examples" / "index.md"
+
+    if not examples_dir.is_dir():
+        return 0, []
+    if not index_file.exists():
+        errors.append("Examples index page not found: docs/docs/examples/index.md")
+        return len(errors), errors
+
+    index_content = index_file.read_text()
+
+    # Directories to skip: not standalone example categories
+    skip = {"__pycache__", "helper"}
+
+    for child in sorted(examples_dir.iterdir()):
+        if not child.is_dir():
+            continue
+        if child.name in skip or child.name.startswith("."):
+            continue
+        # Only check directories that contain at least one .py file
+        if not any(child.rglob("*.py")):
+            continue
+        # Check the directory name appears in the index (as a table entry or heading)
+        if (
+            f"`{child.name}/" not in index_content
+            and f"`{child.name}`" not in index_content
+        ):
+            errors.append(
+                f"Example directory '{child.name}/' is not listed in "
+                f"docs/docs/examples/index.md"
+            )
+
+    return len(errors), errors
+
+
 def validate_doc_imports(docs_dir: Path) -> tuple[int, list[str]]:
     """Verify that mellea imports in documentation code blocks still resolve.
 
@@ -417,6 +466,7 @@ def generate_report(
     rst_docstring_errors: list[str] | None = None,
     stale_errors: list[str] | None = None,
     import_errors: list[str] | None = None,
+    examples_catalogue_errors: list[str] | None = None,
 ) -> dict:
     """Generate validation report.
 
@@ -427,6 +477,8 @@ def generate_report(
         stale_errors = []
     if import_errors is None:
         import_errors = []
+    if examples_catalogue_errors is None:
+        examples_catalogue_errors = []
 
     return {
         "source_links": {
@@ -471,6 +523,11 @@ def generate_report(
             "error_count": len(import_errors),
             "errors": import_errors,
         },
+        "examples_catalogue": {
+            "passed": len(examples_catalogue_errors) == 0,
+            "error_count": len(examples_catalogue_errors),
+            "errors": examples_catalogue_errors,
+        },
         "overall_passed": (
             len(source_link_errors) == 0
             and coverage_passed
@@ -479,6 +536,7 @@ def generate_report(
             and len(anchor_errors) == 0
             and len(stale_errors) == 0
             and len(import_errors) == 0
+            and len(examples_catalogue_errors) == 0
             # rst_docstrings is a warning only — does not fail the build
         ),
     }
@@ -559,6 +617,9 @@ def main():
     static_docs_dir = docs_root / "docs" if docs_root else docs_dir.parent
     _, import_errors = validate_doc_imports(static_docs_dir)
 
+    print("Checking examples catalogue...")
+    _, examples_catalogue_errors = validate_examples_catalogue(docs_root)
+
     # Generate report
     report = generate_report(
         source_link_errors,
@@ -570,6 +631,7 @@ def main():
         rst_docstring_errors,
         stale_errors,
         import_errors,
+        examples_catalogue_errors,
     )
 
     # Print results
@@ -619,6 +681,12 @@ def main():
     if not report["doc_imports"]["passed"]:
         print(f"   {report['doc_imports']['error_count']} errors found")
 
+    print(
+        f"✅ Examples catalogue: {'PASS' if report['examples_catalogue']['passed'] else 'FAIL'}"
+    )
+    if not report["examples_catalogue"]["passed"]:
+        print(f"   {report['examples_catalogue']['error_count']} errors found")
+
     print("\n" + "=" * 60)
     print(f"Overall: {'✅ PASS' if report['overall_passed'] else '❌ FAIL'}")
     print("=" * 60)
@@ -634,6 +702,7 @@ def main():
             + rst_docstring_errors
             + stale_errors
             + import_errors
+            + examples_catalogue_errors
         )
         for error in all_errors:
             print(f"  • {error}")