docs(pipeline): add "Compose Pipelines With Additional Modules" README section and docstring notes

- Add README subsection demonstrating FlowerPowerProject.run and PipelineManager.run with additional_modules
  (examples, module resolution rules, precedence, reload behavior, and CLI note).
- Update PipelineVisualizer docstrings to document additional_modules resolution, reload semantics,
  and example usages for save_dag/show_dag.
- Add doc tasks/proposal files under openspec/changes documenting the docs update and acceptance criteria.
- Small docstring tweak in PipelineManager.run to mention additional_modules resolution and precedence.

Author: legout

README.md

@@ -296,6 +296,59 @@ For quick testing or local runs, you can execute your pipeline synchronously. Th
     ```
 
 
+### Compose Pipelines With Additional Modules
+
+Hamilton can build a DAG from more than one Python module. FlowerPower surfaces this through the `additional_modules` argument so you can split shared setup, teardown, or utility nodes into their own files.
+
+```python
+from flowerpower import FlowerPowerProject
+
+project = FlowerPowerProject.load('.')
+
+# Combine the hello_world pipeline with its setup companion module
+result = project.run(
+    'hello_world',
+    additional_modules=['pipeline_setup'],
+    final_vars=["full_greeting"],
+)
+print(result)
+
+# PipelineManager exposes the same capability
+from flowerpower.pipeline import PipelineManager
+
+pm = PipelineManager(base_dir='.')
+composed = pm.run(
+    name='hello_world',
+    additional_modules=['pipeline_setup'],
+    final_vars=['full_greeting'],
+)
+print(composed)
+
+# Visualize the composed DAG
+pm.visualizer.save_dag(
+    name='hello_world',
+    base_dir='.',
+    additional_modules=['pipeline_setup'],
+)
+```
+
+How module resolution works:
+
+- Each string is imported as-is, with a fallback to the underscored variant (replacing `-` with `_`) and to `pipelines.<name>`.
+- You can mix strings and already-imported module objects in the same list.
+- If multiple modules define the same node, the last module passed to `additional_modules` (and finally the primary pipeline module) wins—matching Hamilton’s precedence rules.
+
+Reload behaviour:
+
+- Setting `reload=True` ensures that every module in `additional_modules` and the main pipeline module is reloaded before execution, making it easy to iterate during development.
+
+Examples:
+
+- The hello-world example demonstrates this pattern: `examples/hello-world/pipelines/setup.py` pairs with `hello_world.py` to provide initialization nodes. The snippets above mirror that structure.
+
+> ℹ️ The Python API currently exposes `additional_modules`. The CLI does not yet forward this option.
+
+
 ## ⚙️ Configuration Overview
 
 FlowerPower uses a layered configuration system:
@@ -381,6 +434,8 @@ print(f"Pipeline config: {info}")
 pm.delete('old_pipeline')
 ```
 
+See [Compose Pipelines With Additional Modules](#compose-pipelines-with-additional-modules) for an example that loads `pipeline_setup` alongside the pipeline module.
+
 **When to use Pipeline-only approach:**
 - Simple synchronous workflows
 - Testing and development
@@ -409,4 +464,4 @@ You can find the full documentation for FlowerPower, including installation inst
 
 ## 📜 License
 
-This project is licensed under the MIT License - see the `LICENSE` file for details. (Placeholder - update with actual license)
+This project is licensed under the MIT License - see the `LICENSE` file for details. (Placeholder - update with actual license)

openspec/changes/docs-add-additional-modules-usage/proposal.md

@@ -0,0 +1,46 @@
+## Why
+The library now supports composing multiple pipeline modules at runtime via `additional_modules` (e.g., `pm.run("pipeline_1", additional_modules=["setup"])`). We should document this capability so users can discover how to:
+- Combine a setup module with a main pipeline
+- Understand import/name resolution rules and precedence
+- Visualize composed DAGs with the visualizer
+
+## What Changes
+- README
+  - Add a dedicated subsection ("Compose Pipelines With Additional Modules") under Python API usage.
+  - Provide examples for both `FlowerPowerProject.run` and `PipelineManager.run` using `additional_modules`.
+  - Mention conflict resolution/precedence (last module wins) and `reload=True` behavior.
+  - Cross-link to example in `examples/hello-world/`.
+- API docstrings
+  - Ensure `additional_modules` is present and clearly described in `PipelineManager.run(...)` and visualizer methods `save_dag`/`show_dag`.
+- Visualizer docs
+  - Show how to pass `additional_modules` to render a composite DAG.
+- Examples
+  - Reference `examples/hello-world/pipelines/setup.py` alongside `hello_world.py` in docs to illustrate a simple composition path.
+- CHANGELOG
+  - Already updated; verify entry under Unreleased.
+
+Non‑functional/documentation-only change. No API changes.
+
+## Impact
+- Files to update:
+  - README.md (new subsection, examples)
+  - Optionally add a focused guide: `docs/guide/additional-modules.md` (if guide section exists)
+  - Verify docstrings for `PipelineManager.run` and `PipelineVisualizer` mention `additional_modules`
+  - Ensure example references align with `examples/hello-world/pipelines/setup.py`
+
+## Risks / Considerations
+- Avoid implying CLI support if CLI doesn’t accept `additional_modules` yet (call out Python API only).
+- Clarify module import resolution attempts (`"name"`, `"name" with '-'→'_'`, and `"pipelines.<name>"`).
+- Note that duplicate node names resolve by standard Hamilton semantics (later modules override earlier ones).
+
+## Acceptance Criteria
+- README contains a clear "Compose Pipelines With Additional Modules" section with runnable snippets.
+- `PipelineManager.run` and visualizer method docstrings mention and describe `additional_modules`.
+- Example code snippet(s) reference hello-world’s `setup.py` and `hello_world.py` to demonstrate composition.
+- No claims about CLI support unless implemented.
+- CHANGELOG reflects feature under Unreleased.
+
+## Archival
+This is a docs-only change. After deployment, archive with:
+`openspec archive docs-add-additional-modules-usage --skip-specs --yes`
+

openspec/changes/docs-add-additional-modules-usage/tasks.md

@@ -0,0 +1,18 @@
+## 1. Documentation Updates
+- [x] 1.1 README: add "Compose Pipelines With Additional Modules" section with examples for `project.run(...)` and `pm.run(...)` using `additional_modules=["setup"]`.
+- [x] 1.2 README: document precedence (last module passed wins on duplicate node names) and `reload=True` behavior (reloads all loaded modules).
+- [x] 1.3 Visualizer docs: show `additional_modules` usage in `save_dag`/`show_dag` examples.
+- [x] 1.4 Cross-reference examples: highlight `examples/hello-world/pipelines/setup.py` with `hello_world.py` for composition.
+- [x] 1.5 API docstrings: verify/expand `additional_modules` param documentation in `PipelineManager.run` and `PipelineVisualizer` methods.
+- [x] 1.6 Confirm CHANGELOG Unreleased entry includes this feature.
+
+## 2. Optional Guides (if docs site in use)
+- [ ] 2.1 Create `docs/guide/additional-modules.md` with deeper explanation (import resolution, tips, troubleshooting, best practices).
+
+## 3. Validation
+- [x] 3.1 Render README locally to verify code blocks and formatting.
+- [ ] 3.2 (If docs site) run docs build locally to ensure no broken links.
+
+## 4. Rollout
+- [ ] 4.1 Submit PR for review.
+- [ ] 4.2 After merge/deploy, archive change with `openspec archive docs-add-additional-modules-usage --skip-specs --yes`.

src/flowerpower/pipeline/manager.py

@@ -381,6 +381,11 @@ def run(
                 additional_modules (list[str | ModuleType] | None): Extra modules to
                     load alongside the primary pipeline for Hamilton execution.
                     Example: ["setup", setup_module]
+                    Notes:
+                        - String entries are attempted as-is, with fallbacks to a
+                          hyphen-to-underscore variant and to `pipelines.<name>`.
+                        - When multiple modules provide the same node, later modules
+                          take precedence following Hamilton semantics.
                 reload (bool): Force reload of pipeline configuration.
                 log_level (str | None): Logging level for the execution. Default None uses project config.
                     Valid values: "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"

src/flowerpower/pipeline/visualizer.py

@@ -47,6 +47,13 @@ def _get_dag_object(
         Raises:
             ImportError: If the module cannot be loaded.
 
+        Notes:
+            - String entries in ``additional_modules`` are resolved using the same
+              strategy as pipeline execution: the raw name, a hyphen-to-underscore
+              variant, and ``pipelines.<name>`` are attempted in order.
+            - ``reload=True`` reloads every module (primary + additional) before the
+              driver is constructed, which mirrors runtime execution behaviour.
+
         """
         # Load pipeline-specific config
         pipeline_cfg = PipelineConfig.load(name=name, fs=self._fs)
@@ -90,6 +97,10 @@ def save_dag(
         Raises:
             ImportError: If any module cannot be loaded.
 
+        Notes:
+            - ``additional_modules`` uses the same resolution strategy as pipeline execution.
+            - Pass ``reload=True`` to reload the primary and additional modules before rendering.
+
         Example:
             >>> from flowerpower.pipeline.visualizer import PipelineVisualizer
             >>> visualizer = PipelineVisualizer(project_cfg, fs)
@@ -99,6 +110,7 @@ def save_dag(
             ...     format="png",
             ...     additional_modules=["setup"],
             ... )
+            >>> # Compose hello_world + setup from examples/hello-world/pipelines/
         """
         dag = self._get_dag_object(
             name=name, reload=reload, additional_modules=additional_modules
@@ -160,6 +172,10 @@ def show_dag(
         Raises:
             ImportError: If any module cannot be loaded.
 
+        Notes:
+            - ``additional_modules`` follows the same resolution strategy as pipeline execution.
+            - Use ``reload=True`` to pull in code changes from every module before rendering.
+
         Example:
             >>> from flowerpower.pipeline.visualizer import PipelineVisualizer
             >>> visualizer = PipelineVisualizer(project_cfg, fs)
@@ -169,6 +185,7 @@ def show_dag(
             ...     format="png",
             ...     additional_modules=["setup"],
             ... )
+            >>> # Compose hello_world + setup modules during development
         """
         dag = self._get_dag_object(
             name=name, reload=reload, additional_modules=additional_modules