From 95aa3352e684b53f3eb6015c5dd3b0279ab98458 Mon Sep 17 00:00:00 2001
From: michaelj <michaelj@ie.ibm.com>
Date: Fri, 30 Jan 2026 17:11:58 +0000
Subject: [PATCH 1/8] feat(core): agent guidelines

- general development
- plugin development
- querying data
- creating space/operation YAMLS
---
 .cursor/commands/review.md                    |  15 +
 .cursor/rules/general-development.mdc         | 133 +++++++
 .cursor/rules/plugin-development.mdc          | 280 ++++++++++++++
 .../skills/formulate-ado-problems/SKILL.md    | 196 ++++++++++
 .../skills/formulate-ado-problems/examples.md | 240 ++++++++++++
 .../formulate-ado-problems/reference.md       | 199 ++++++++++
 .../yaml-examples/error-fix-batch-size.yaml   |   7 +
 .../yaml-examples/example1-operation.yaml     |  17 +
 .../yaml-examples/example1-space.yaml         |  18 +
 .../yaml-examples/example2-space.yaml         |  20 +
 .../yaml-examples/example3-space.yaml         |  22 ++
 .../yaml-examples/example4-space.yaml         |  22 ++
 .../yaml-examples/example5-space.yaml         |  18 +
 .../example6-actuator-config.yaml             |   9 +
 .../yaml-examples/example6-operation.yaml     |  14 +
 .../reference-experiment-format.yaml          |   9 +
 .../reference-operation-structure.yaml        |  14 +
 .../reference-pattern1-simple-space.yaml      |  11 +
 ...ference-pattern2-multiple-experiments.yaml |  13 +
 .../reference-pattern3-parameterized.yaml     |   9 +
 .../reference-pattern4-optional-property.yaml |  11 +
 .../reference-property-domain.yaml            |   8 +
 .../yaml-examples/skill-manual-structure.yaml |  14 +
 .../skill-operation-structure.yaml            |  15 +
 .../skill-property-domain-continuous.yaml     |   5 +
 ...-property-domain-discrete-categorical.yaml |   5 +
 ...kill-property-domain-discrete-numeric.yaml |   6 +
 .cursor/skills/query-ado-data/SKILL.md        | 296 +++++++++++++++
 pyproject.toml                                |   1 +
 uv.lock                                       | 354 +++++++++++++++---
 30 files changed, 1932 insertions(+), 49 deletions(-)
 create mode 100644 .cursor/commands/review.md
 create mode 100644 .cursor/rules/general-development.mdc
 create mode 100644 .cursor/rules/plugin-development.mdc
 create mode 100644 .cursor/skills/formulate-ado-problems/SKILL.md
 create mode 100644 .cursor/skills/formulate-ado-problems/examples.md
 create mode 100644 .cursor/skills/formulate-ado-problems/reference.md
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/error-fix-batch-size.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example1-operation.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example1-space.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example2-space.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example3-space.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example4-space.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example5-space.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example6-actuator-config.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/example6-operation.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-experiment-format.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-operation-structure.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern1-simple-space.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern2-multiple-experiments.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern3-parameterized.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern4-optional-property.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/reference-property-domain.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/skill-manual-structure.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/skill-operation-structure.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-continuous.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-categorical.yaml
 create mode 100644 .cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-numeric.yaml
 create mode 100644 .cursor/skills/query-ado-data/SKILL.md

diff --git a/.cursor/commands/review.md b/.cursor/commands/review.md
new file mode 100644
index 000000000..52271c8a9
--- /dev/null
+++ b/.cursor/commands/review.md
@@ -0,0 +1,15 @@
+# review
+
+- Review the changes in the current branch
+- Be picky
+- Use general-development rules to evaluate code
+- Link comments to code
+- Format report with following sections (omit if not relevant)
+  - Overview: What is changed
+  - Bugs:Any potential bugs
+  - Critical Issues: Critical problems with implementation or structure
+  - Medium Issues: Issues that should be considered but may not need to be
+    fixed now
+  - Style Issues: Any style changes that should be made
+  - Linting Issues: Issues raised by the linters
+- Write review to md file also
diff --git a/.cursor/rules/general-development.mdc b/.cursor/rules/general-development.mdc
new file mode 100644
index 000000000..051f05771
--- /dev/null
+++ b/.cursor/rules/general-development.mdc
@@ -0,0 +1,133 @@
+---
+description: General development guidelines for ad-ado - code style, testing, quality checks, and commit standards
+alwaysApply: true
+---
+
+# General Development Guidelines for ado
+
+These guidelines apply to all code development in the ad-orchestrator codebase.
+
+## Code Structure
+
+- **orchestrator**: main Python package
+  - **schema**: pydantic models for properties, entities, experiments, and measurement results
+  - **core**: pydantic models and associated code for the core resource types managed by ado:
+    - discoveryspace
+    - operation
+    - samplestore
+    - datacontainer
+    - actuatorconfiguration
+  - **modules/actuators**: defines actuators, custom experiments, and their associated management code (plugins, registry)
+  - **modules/operators**: defines operators and their associated management code (plugins, collections, orchestration)
+  - **utilities**: common utilities
+  - **cli**: ado CLI
+  - **metastore**: code defining and interacting with the metastore, which stores core resource types
+- **tests**: unit and integration tests (pytest)
+- **plugins**: actuator, operator, and custom_experiment plugins
+- **website**: mkdocs website and documentation
+- **examples**: examples of using ado
+
+### Structure Guidelines
+
+- Place new code in the most specific existing subpackage.
+- Do not create new top-level packages unless explicitly instructed.
+
+---
+
+## Code Style
+
+- Use PEP8 naming conventions for new code.
+- **Exception**: use camelCase for fields of pydantic models.
+- Do not modify existing names unless explicitly asked, even if they do not follow PEP8.
+- Use type annotations on all functions and methods, including return types.
+- Add docstrings to all functions and methods.
+- Use the pydantic annotated form for pydantic fields
+  (see `orchestrator/schema/entity.py`).
+- Use discriminated unions when a type is a union
+  (see `ExperimentType` in `orchestrator/schema/experiment.py`).
+- Use the `Defaultable` type from `orchestrator/utilities/pydantic` for pydantic fields that:
+  - accept `None`, but
+  - are always defaulted to a different type.
+- Use absolute imports within the repository unless the file already uses relative imports.
+
+---
+
+## Developer Tools
+
+- All development tools (ruff, black, pytest, etc.) are available in the project’s **uv-managed virtual environment**.
+- Do not install tools globally.
+- Use the following pattern to execute tools:
+
+    uv run TOOLNAME
+
+---
+
+## Code Development
+
+Use Test Driven Development
+
+- Write tests first
+    - Do not create mock implementations
+- Run pytest: confirm tests fail
+- Implement the code to be tested
+- Run pytest: check tests
+- Iterate until tests pass
+
+## Writing Tests
+
+- Check for existing fixtures before creating new ones:
+  - `tests/fixtures/`
+- Do not mock by default; prefer integration tests.
+- Test the full lifecycle for pydantic models:
+    create → dump → create from dump
+
+## Code Linting
+
+- Linting must be run after any code changes and must pass before running tests.
+- Run **black** after changes:
+
+   uv run black $DIR
+
+- Run **ruff** after changes:
+
+   uv run ruff check --fix $DIR
+
+- Fix any issues reported by ruff that it could not fix automatically.
+- Run black and ruff at directory level for efficiency (e.g. `orchestrator/`, `plugins/`, `tests/`).
+- Run the mkdocs linter only when creating or modifying documentation in the `website/` directory:
+
+    uv run markdownlint-cli2 NEW_OR_CHANGED_FILE --fix
+
+- Run **yamlfix** after YAML changes
+
+   uv run yamlfix $FILE
+
+
+---
+
+## Code Testing
+
+- Each subpackage has a corresponding test directory under `tests/`, for example:
+  - `schema/`
+  - `core/`
+  - `actuators/`
+  - `operators/`
+  - `metastore/`
+  - `cli/`
+- As a final validation step, run tests for all impacted subpackages.
+- All tests must pass before submitting changes.
+- Ensure the virtual environment is correctly set up before running tests:
+
+    uv sync --reinstall --group test --group dev
+
+---
+
+## YAML Testing
+
+- Test any new or modified ado resource YAML using:
+
+    ado create RESOURCETYPE -f FILE --dry-run
+
+---
+
+- For plugin development, see [plugin-development.mdc](plugin-development.mdc)
\ No newline at end of file
diff --git a/.cursor/rules/plugin-development.mdc b/.cursor/rules/plugin-development.mdc
new file mode 100644
index 000000000..0f4e44e8d
--- /dev/null
+++ b/.cursor/rules/plugin-development.mdc
@@ -0,0 +1,280 @@
+---
+description: Guidelines for developing ado plugins (actuators, operators, custom_experiments)
+globs: "{plugins,examples}/**/*"
+alwaysApply: false
+---
+
+# Plugin Development Guidelines
+
+These guidelines apply when developing plugins for ado.
+Plugins are developed under `plugins/` or `examples/` directories.
+All general development guidelines from `general-development.mdc` also apply.
+
+---
+
+## Plugin Structure
+
+### Package Organization
+
+- **Actuators**: Each actuator is its own package under `plugins/actuators/`
+- **Operators**: Each operator is its own package under `plugins/operators/`
+- **Custom Experiments**: Can have multiple custom experiments in a single package under `plugins/custom_experiments/`
+
+### Directory Layout
+
+Each plugin package should contain:
+
+- `pyproject.toml` - Package configuration
+- `tests/` - Unit and integration tests (keep within the plugin package)
+- YAML examples - Example discoveryspace and operation files for the plugin
+- Plugin implementation code
+
+---
+
+## Package Setup
+
+### Using setuptools_scm for Versioning
+
+Configure `pyproject.toml` to use `setuptools_scm` for automatic versioning:
+
+```toml
+[build-system]
+requires = ["setuptools", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+root = "../../../"  # Points to repo root
+
+[project]
+name = "your-plugin-name"
+dynamic = ["version"]  # Version set automatically by setuptools_scm
+```
+
+### Dependencies
+
+**Always include ado-core** in dependencies:
+
+```toml
+[project]
+dependencies = [
+    "ado-core",
+    # ... other dependencies
+]
+```
+
+### Adding Dependencies with uv
+
+Use `uv` to add new dependencies to your plugin:
+
+```bash
+cd plugins/actuators/your_plugin/
+uv add package-name
+```
+
+---
+
+## Plugin Registration
+
+### Actuators: Namespaced Packages
+
+Actuators use namespaced packages and require:
+
+1. Package structure under a namespace
+2. `actuator_definitions.yaml` file
+3. Optional `experiments.yaml` file
+
+```toml
+[tool.setuptools.package-data]
+your_actuator = [
+    "actuator_definitions.yaml",  # Required
+    "experiments.yaml"             # Optional
+]
+```
+
+### Operators and Custom Experiments: Entry Points
+
+Operators and custom experiments use entry points in `pyproject.toml`:
+
+**Operator Example:**
+
+```toml
+[project.entry-points."ado.operators"]
+ado-ray-tune = "ado_ray_tune.operator_function"
+```
+
+**Custom Experiment Example:**
+
+```toml
+[project.entry-points."ado.custom_experiments"]
+min_gpu_experiment = "autoconf.min_gpu_recommender"
+```
+
+---
+
+## Custom Experiments
+
+### Decorator Requirements
+
+Custom experiments **must** use the `@custom_experiment` decorator correctly:
+
+```python
+from orchestrator.modules.actuators.custom_experiments import custom_experiment
+from orchestrator.schema.property import ConstitutiveProperty
+
+# Define your properties
+MyProperty = ConstitutiveProperty(...)
+
+@custom_experiment(
+    required_properties=[MyProperty, ...],
+    optional_properties=[...],
+    output_property_identifiers=["output1", "output2"],
+    metadata={
+        "description": "Clear description of what this experiment does"
+    },
+    parameterization={},
+)
+def my_custom_experiment(entity, actuator, parameterization):
+    # Implementation
+    return results
+```
+
+**Key Points:**
+
+- Specify all `required_properties` that the experiment needs
+- List any `optional_properties`
+- Define `output_property_identifiers` for measurement results
+- Include descriptive metadata
+- Function signature must match: `(entity, actuator, parameterization)`
+
+---
+
+## Testing Requirements
+
+### Test Location
+
+Keep tests **within the plugin package**, not in the top-level `tests/` directory.
+
+### Testing Checklist
+
+Before considering a plugin complete, verify:
+
+- [ ] **Experiment execution**: Use `run_experiment` tool to verify custom_experiment or actuator experiments can run successfully
+- [ ] **Valid DiscoverySpace YAML**: Create and validate a discoveryspace YAML that uses the experiment/actuator
+  ```bash
+  ado create discoveryspace -f space.yaml --dry-run
+  ```
+- [ ] **Valid Operation YAML**: Create and validate an operation YAML that uses the operator
+  ```bash
+  ado create operation -f operation.yaml --dry-run
+  ```
+- [ ] **Unit tests pass**: Run pytest on the plugin package
+  ```bash
+  uv run pytest plugins/your_plugin_type/your_plugin/tests/
+  ```
+
+### Example YAML Files
+
+Include example YAML files in your plugin package that demonstrate:
+
+- How to configure a discoveryspace with your actuator/experiment
+- How to configure an operation with your operator
+- Different use cases or configurations
+
+---
+
+## Linting
+
+After making changes to plugin code, run linting at the plugin directory level:
+
+```bash
+cd plugins/actuators/your_plugin/
+uv run black .
+uv run ruff check --fix .
+```
+
+Fix any issues that ruff cannot automatically resolve.
+
+---
+
+## Complete pyproject.toml Examples
+
+### Actuator Example
+
+```toml
+[build-system]
+requires = ["setuptools", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+root = "../../../"
+
+[tool.setuptools.packages.find]
+where = ["."]
+exclude = ["build", "build.*", "examples"]
+
+[tool.setuptools.package-data]
+my_actuator = [
+    "actuator_definitions.yaml",
+    "experiments.yaml"
+]
+
+[project]
+name = "my-actuator"
+description = "Description of your actuator"
+dynamic = ["version"]
+dependencies = [
+    "ado-core",
+]
+```
+
+### Operator Example
+
+```toml
+[build-system]
+requires = ["setuptools", "setuptools_scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+root = "../../../"
+
+[project]
+name = "my-operator"
+dynamic = ["version"]
+dependencies = [
+    "ado-core",
+]
+
+[project.entry-points."ado.operators"]
+my-operator = "my_operator.operator_function"
+```
+
+### Custom Experiment Example
+
+```toml
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-custom-experiment"
+description = "Description of your custom experiment"
+dynamic = ["version"]
+dependencies = [
+    "ado-core",
+]
+
+[project.entry-points."ado.custom_experiments"]
+my_experiment = "my_package.my_experiment"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+pattern = "default-unprefixed"
+fallback-version = "0.0.0"
+tagged-metadata = true
+dirty = true
+bump = true
+```
diff --git a/.cursor/skills/formulate-ado-problems/SKILL.md b/.cursor/skills/formulate-ado-problems/SKILL.md
new file mode 100644
index 000000000..2ee7958a0
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/SKILL.md
@@ -0,0 +1,196 @@
+---
+name: formulate-ado-problems
+description: |
+  Formulates problems for execution with ado by creating discoveryspace and
+  operation YAML files. Guides through experiment selection, space creation,
+  validation, operation configuration, and parameterization. Use when the user
+  wants to create discoveryspace or operation YAML files, configure experiments,
+  set up entity spaces, or formulate problems for ado execution.
+---
+
+# Formulating Problems for ado Execution
+
+This skill guides you through creating discoveryspace and operation YAML files
+to formulate problems for execution with ado.
+
+## Workflow Overview
+
+The process has two main phases:
+
+1. **Create DiscoverySpace YAML** - Define experiments and entity space
+2. **Create Operation YAML** - Configure how to explore/analyze the space
+
+Each phase follows: choose → create → validate → iterate.
+
+## Phase 1: Create DiscoverySpace YAML
+
+### Step 1a: Choose Experiments
+
+**List available experiments:**
+
+```bash
+uv run ado get actuators --details
+```
+
+**Describe a specific experiment:**
+
+```bash
+uv run ado describe experiment $EXPERIMENT_ID
+```
+
+**Key information to gather:**
+
+- Required constitutive properties (must be in entity space)
+- Optional properties (can use defaults or add to entity space)
+- Target properties (what the experiment measures)
+
+### Step 1b: Create DiscoverySpace YAML
+
+**Generate initial template from experiment:**
+
+```bash
+uv run ado template space --from-experiment $EXPERIMENT_ID > space.yaml
+```
+
+**Manual structure:**
+
+See [skill-manual-structure.yaml](yaml-examples/skill-manual-structure.yaml).
+
+### Step 1c: Validate DiscoverySpace YAML
+
+```bash
+uv run ado create space -f space.yaml --dry-run
+```
+
+### Step 1d: Iterate Until Valid
+
+Fix validation errors and repeat validation until successful.
+
+## Phase 2: Create Operation YAML
+
+### Step 2a: Choose Operator
+
+**List available operators:**
+
+```bash
+uv run ado get operators
+```
+
+**Get operator template:**
+
+```bash
+uv run ado template operation --operator-name $OPERATOR_NAME > operation.yaml
+```
+
+### Step 2b: Decide Parameters
+
+Review the template and configure parameters based on:
+
+- User's query/goals
+- Operator documentation
+- Example operations in `examples/`
+
+### Step 2c: Create Operation YAML
+
+**Structure:**
+
+See [skill-operation-structure.yaml](yaml-examples/skill-operation-structure.yaml).
+
+### Step 2d: Validate Operation YAML
+
+```bash
+uv run ado create operation -f operation.yaml --dry-run
+```
+
+### Step 2e: Iterate Until Valid
+
+Fix validation errors and repeat validation until successful.
+
+## Critical Rules
+
+### Experiment Selection Rules
+
+1. **Choose experiments first** - Before defining entity space
+2. **All required inputs must be in entity space** - Every `requiredProperties`
+   (constitutive) from experiments must have a corresponding property in
+   `entitySpace`
+3. **Optional properties** - Only add to entity space if necessary to answer
+   user's query. Explain why.
+4. **Default values** - Only change default values of optional properties if
+   necessary. Explain why.
+
+### Entity Space Refinement Rules
+
+1. **Refine domains to reduce size** - Narrow property domains based on
+   user's query. Explain the refinement.
+2. **No redundant dimensions** - All entity space properties should be
+   required by at least one experiment (validation will catch this)
+3. **Domain compatibility** - Entity space property domains must be
+   compatible with experiment requirements (subdomain or equal)
+
+### Property Domain Guidelines
+
+**Discrete (categorical):**
+
+See [skill-property-domain-discrete-categorical.yaml](yaml-examples/skill-property-domain-discrete-categorical.yaml).
+
+**Discrete (numeric):**
+
+See [skill-property-domain-discrete-numeric.yaml](yaml-examples/skill-property-domain-discrete-numeric.yaml).
+
+**Continuous:**
+
+See [skill-property-domain-continuous.yaml](yaml-examples/skill-property-domain-continuous.yaml).
+
+## Validation Checklist
+
+Before finalizing, verify:
+
+- [ ] All required experiment properties are in entity space
+- [ ] Entity space domains are compatible with experiment requirements
+- [ ] No redundant entity space dimensions
+- [ ] Optional properties only added if necessary (with explanation)
+- [ ] Default values only changed if necessary (with explanation)
+- [ ] Domain refinements explained
+- [ ] DiscoverySpace YAML validates (`--dry-run`)
+- [ ] Operation YAML validates (`--dry-run`)
+
+## Common Issues and Solutions
+
+**Issue:** Validation error "required property not in entity space"
+
+- **Solution:** Add the missing property to `entitySpace` with appropriate domain
+
+**Issue:** Validation error "domain incompatible"
+
+- **Solution:** Ensure entity space domain is a subdomain of experiment's
+  required domain
+
+**Issue:** Validation error "redundant dimension"
+
+- **Solution:** Remove properties from entity space that aren't required by
+  any experiment
+
+**Issue:** Operation validation fails
+
+- **Solution:** Check operator parameters match schema. Use `--include-schema`
+  flag with template command.
+
+## Additional Resources
+
+- For detailed schema information, see [reference.md](reference.md)
+- For example workflows, see [examples.md](examples.md)
+- For Pydantic model details, examine:
+  - `orchestrator/schema/experiment.py`
+  - `orchestrator/schema/measurementspace.py`
+  - `orchestrator/schema/entityspace.py`
+  - `orchestrator/core/discoveryspace/config.py`
+  - `orchestrator/core/operation/operation.py`
+
+## References
+
+When modifying or creating code while using this skill, follow:
+
+- [general-development.mdc](../../rules/general-development.mdc)
+- [plugin-development.mdc](../../rules/plugin-development.mdc) (if working
+  with plugins)
diff --git a/.cursor/skills/formulate-ado-problems/examples.md b/.cursor/skills/formulate-ado-problems/examples.md
new file mode 100644
index 000000000..3b9a19d34
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/examples.md
@@ -0,0 +1,240 @@
+# Examples: ado Problem Formulation
+
+Concrete examples of formulating problems for ado execution.
+
+## Example 1: Simple Hyperparameter Optimization
+
+**User Query:** "I want to optimize learning rate and batch size for model training"
+
+### Step 1: Choose Experiments
+
+```bash
+uv run ado get actuators --details
+# Find: TrainerActuator.train_model
+uv run ado describe experiment TrainerActuator.train_model
+```
+
+**Experiment details:**
+
+- Required: `learning_rate`, `batch_size`
+- Optional: `optimizer` (default: "sgd"), `epochs` (default: 10)
+- Targets: `accuracy`, `loss`
+
+### Step 2: Create DiscoverySpace YAML
+
+See [example1-space.yaml](yaml-examples/example1-space.yaml).
+
+**Explanation:**
+
+- Added `learning_rate` and `batch_size` to entity space (required properties)
+- Left `optimizer` and `epochs` as defaults (not needed for user's query)
+- Refined domains based on typical hyperparameter ranges
+
+### Step 3: Validate
+
+```bash
+uv run ado create space -f space.yaml --dry-run
+```
+
+### Step 4: Create Operation YAML
+
+See [example1-operation.yaml](yaml-examples/example1-operation.yaml).
+
+### Step 5: Validate Operation
+
+```bash
+uv run ado create operation -f operation.yaml --dry-run
+```
+
+## Example 2: Multi-Experiment Pipeline
+
+**User Query:** "I want to train models and then evaluate them on a test set"
+
+### Example 2 Step 1: Choose Experiments
+
+```bash
+uv run ado describe experiment TrainerActuator.train_model
+# Required: learning_rate, batch_size
+# Targets: accuracy, loss
+
+uv run ado describe experiment EvaluatorActuator.evaluate_model
+# Required: accuracy (ObservedProperty from train_model)
+# Targets: test_accuracy, test_loss
+```
+
+### Example 2 Step 2: Create DiscoverySpace YAML
+
+See [example2-space.yaml](yaml-examples/example2-space.yaml).
+
+**Explanation:**
+
+- Added required constitutive properties (`learning_rate`, `batch_size`)
+- Included both experiments - `evaluate_model` depends on `train_model`'s output
+- Dependency automatically handled (evaluate_model requires accuracy from
+  train_model)
+
+### Example 2 Step 3: Validate
+
+```bash
+uv run ado create space -f space.yaml --dry-run
+```
+
+## Example 3: Exploring Optional Properties
+
+**User Query:** "I want to compare different optimizers (adam, sgd, rmsprop)
+with different learning rates"
+
+### Example 3 Step 1: Choose Experiments
+
+```bash
+uv run ado describe experiment TrainerActuator.train_model
+# Required: learning_rate, batch_size
+# Optional: optimizer (default: "sgd")
+```
+
+### Example 3 Step 2: Create DiscoverySpace YAML
+
+See [example3-space.yaml](yaml-examples/example3-space.yaml).
+
+**Explanation:**
+
+- Added `optimizer` to entity space (necessary to answer user's query about
+  comparing optimizers)
+- Reduced `batch_size` values to keep space manageable
+- All three optimizers will be explored
+
+### Example 3 Step 3: Validate
+
+```bash
+uv run ado create space -f space.yaml --dry-run
+```
+
+## Example 4: Custom Parameterization
+
+**User Query:** "I want to train with adam optimizer specifically, but explore
+learning rates"
+
+### Example 4 Step 1: Choose Experiments
+
+```bash
+uv run ado describe experiment TrainerActuator.train_model
+# Optional: optimizer (default: "sgd")
+```
+
+### Example 4 Step 2: Create DiscoverySpace YAML
+
+See [example4-space.yaml](yaml-examples/example4-space.yaml).
+
+**Explanation:**
+
+- Used parameterization to set `optimizer` to "adam" (not exploring it, just
+  fixing it)
+- Only `learning_rate` and `batch_size` in entity space (required properties)
+- Custom parameterization overrides default "sgd"
+
+### Example 4 Step 3: Validate
+
+```bash
+uv run ado create space -f space.yaml --dry-run
+```
+
+## Example 5: Domain Refinement
+
+**User Query:** "I want to fine-tune learning rate around 0.01"
+
+### Example 5 Step 1: Choose Experiments
+
+```bash
+uv run ado describe experiment TrainerActuator.train_model
+# Required: learning_rate (domain: [0.0001, 1.0])
+```
+
+### Example 5 Step 2: Create DiscoverySpace YAML
+
+See [example5-space.yaml](yaml-examples/example5-space.yaml).
+
+**Explanation:**
+
+- Refined `learning_rate` domain from `[0.0001, 1.0]` to `[0.005, 0.02]`
+  (narrower range around 0.01)
+- This reduces the search space and focuses on the region of interest
+- Domain is still compatible (subdomain of experiment's domain)
+
+### Example 5 Step 3: Validate
+
+```bash
+uv run ado create space -f space.yaml --dry-run
+```
+
+## Example 6: Operation with Actuator Configuration
+
+**User Query:** "Run random walk with GPU configuration"
+
+### Step 1: Create DiscoverySpace (from previous examples)
+
+### Step 2: Create Actuator Configuration
+
+See [example6-actuator-config.yaml](yaml-examples/example6-actuator-config.yaml).
+
+```bash
+uv run ado create actuatorconfiguration -f gpu_config.yaml
+# Returns: actuatorconfiguration-xyz789
+```
+
+### Step 3: Create Operation YAML
+
+See [example6-operation.yaml](yaml-examples/example6-operation.yaml).
+
+**Explanation:**
+
+- Referenced actuator configuration created in Step 2
+- Operation will use GPU settings when running experiments
+
+### Step 4: Validate
+
+```bash
+uv run ado create operation -f operation.yaml --dry-run
+```
+
+## Common Validation Errors and Fixes
+
+### Error: "required property not in entity space"
+
+**Error message:**
+
+```text
+ValueError: Identified a measurement space constitutive property not in
+entity space: batch_size
+```
+
+**Fix:** Add missing property to entity space:
+
+See [error-fix-batch-size.yaml](yaml-examples/error-fix-batch-size.yaml).
+
+### Error: "domain incompatible"
+
+**Error message:**
+
+```text
+ValueError: Identified an entity space dimension not compatible with the
+measurement space requirements.
+```
+
+**Fix:** Ensure entity space domain is subdomain of experiment's domain:
+
+```text
+# Experiment requires: [0.0001, 1.0]
+# Entity space: [0.001, 0.1] ✓ (subdomain)
+# Entity space: [0.5, 2.0] ✗ (not subdomain)
+```
+
+### Error: "redundant dimension"
+
+**Error message:**
+
+```text
+ValueError: Identified an entity space dimension that is not required for any experiment
+```
+
+**Fix:** Remove properties not required by any experiment, or add an experiment
+that requires it.
diff --git a/.cursor/skills/formulate-ado-problems/reference.md b/.cursor/skills/formulate-ado-problems/reference.md
new file mode 100644
index 000000000..833d11cd6
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/reference.md
@@ -0,0 +1,199 @@
+# Reference: ado Problem Formulation
+
+Detailed reference information for formulating problems in ado.
+
+## DiscoverySpace Configuration Schema
+
+### Core Fields
+
+**sampleStoreIdentifier** (required):
+
+- String identifier of the sample store
+- Default: `"default"`
+- Use existing store or create new one
+
+**entitySpace** (optional):
+
+- List of `ConstitutiveProperty` objects
+- Defines dimensions of the space
+- Required if space needs to generate new entities
+
+**experiments** (optional):
+
+- `MeasurementSpaceConfiguration` or list of `ExperimentReference`
+- Defines what experiments to run
+- Can be empty if only using existing entities
+
+**metadata** (optional):
+
+- `ConfigurationMetadata` object
+- Name, description, labels, custom fields
+
+### Experiment Reference Format
+
+See [reference-experiment-format.yaml](yaml-examples/reference-experiment-format.yaml).
+
+## Entity Space Property Schema
+
+### ConstitutiveProperty Structure
+
+See [reference-property-domain.yaml](yaml-examples/reference-property-domain.yaml).
+
+### Variable Types
+
+**DISCRETE_VARIABLE_TYPE:**
+
+- Numeric values from a finite set
+- Use `values` for explicit list: `[1, 2, 4, 8]`
+- Use `domainRange` + `interval` for ranges: `domainRange: [1, 10], interval: 1`
+
+**CONTINUOUS_VARIABLE_TYPE:**
+
+- Real-valued range
+- Requires `domainRange: [min, max]`
+- Cannot enumerate all values
+
+**CATEGORICAL_VARIABLE_TYPE:**
+
+- String or other categorical values
+- Requires `values: ["option1", "option2", ...]`
+
+**BINARY_VARIABLE_TYPE:**
+
+- Boolean or two-value categorical
+- No domain specification needed
+
+## Operation Configuration Schema
+
+### Core Structure
+
+See [reference-operation-structure.yaml](yaml-examples/reference-operation-structure.yaml).
+
+### Operation Types
+
+- `search` - Exploration/optimization operations (e.g., random_walk, ray_tune)
+- `modify` - Space modification operations
+- `characterize` - Analysis/characterization operations
+- `compare` - Comparison operations
+- `fuse` - Space fusion operations
+- `learn` - Learning operations
+
+## Experiment Properties
+
+### Required Properties
+
+From `experiment.requiredProperties`:
+
+- **ConstitutiveProperty**: Must be in entity space
+- **ObservedProperty**: Must be measured by another experiment in the space
+
+### Optional Properties
+
+From `experiment.optionalProperties`:
+
+- Have default values in `experiment.defaultParameterization`
+- Can be:
+  - Left as defaults (recommended unless user needs to vary them)
+  - Added to entity space (if user wants to explore them)
+  - Custom parameterized (if user needs specific non-default values)
+
+### Target Properties
+
+From `experiment.targetProperties`:
+
+- What the experiment measures
+- Become `ObservedProperty` instances after measurement
+- Can be used as inputs to dependent experiments
+
+## Domain Compatibility Rules
+
+### Subdomain Relationship
+
+Entity space property domain must be a **subdomain** of experiment's required
+property domain:
+
+- For discrete: All entity space values must be in experiment's domain values
+- For continuous: Entity space range must be within experiment's range
+- For categorical: Entity space values must be subset of experiment's
+  values
+
+### Validation
+
+ado validates:
+
+1. All required constitutive properties are in entity space
+2. Entity space domains are compatible (subdomain check)
+3. No redundant dimensions (all entity space properties required by at least
+   one experiment)
+4. Optional properties in entity space don't conflict with parameterization
+
+## Common Patterns
+
+### Pattern 1: Single Experiment, Simple Space
+
+See [reference-pattern1-simple-space.yaml](yaml-examples/reference-pattern1-simple-space.yaml).
+
+### Pattern 2: Multiple Experiments with Dependencies
+
+See [reference-pattern2-multiple-experiments.yaml](yaml-examples/reference-pattern2-multiple-experiments.yaml).
+
+### Pattern 3: Parameterized Experiment
+
+See [reference-pattern3-parameterized.yaml](yaml-examples/reference-pattern3-parameterized.yaml).
+
+### Pattern 4: Optional Property in Entity Space
+
+See [reference-pattern4-optional-property.yaml](yaml-examples/reference-pattern4-optional-property.yaml).
+
+## Validation Commands Reference
+
+**DiscoverySpace:**
+
+```bash
+uv run ado create space -f FILE.yaml --dry-run
+```
+
+**Operation:**
+
+```bash
+uv run ado create operation -f FILE.yaml --dry-run
+```
+
+**With schema details:**
+
+```bash
+uv run ado template space --include-schema
+uv run ado template operation --operator-name NAME --include-schema
+```
+
+## Template Commands Reference
+
+**Space from experiment:**
+
+```bash
+uv run ado template space --from-experiment ACTUATOR.EXPERIMENT > space.yaml
+```
+
+**Operation template:**
+
+```bash
+uv run ado template operation --operator-name OPERATOR_NAME > operation.yaml
+```
+
+**List experiments:**
+
+```bash
+uv run ado get actuators --details
+```
+
+**Describe experiment:**
+
+```bash
+uv run ado describe experiment ACTUATOR.EXPERIMENT
+```
+
+**List operators:**
+
+```bash
+uv run ado get operators
+```
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/error-fix-batch-size.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/error-fix-batch-size.yaml
new file mode 100644
index 000000000..1aae3c996
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/error-fix-batch-size.yaml
@@ -0,0 +1,7 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+entitySpace:
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [16, 32, 64]
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example1-operation.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example1-operation.yaml
new file mode 100644
index 000000000..9d0021290
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example1-operation.yaml
@@ -0,0 +1,17 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+spaces:
+  - space-abc123 # From Step 3
+operation:
+  module:
+    operatorName: random_walk
+    operationType: search
+  parameters:
+    numberEntities: 50
+    batchSize: 1
+    samplerConfig:
+      mode: sequential
+      samplerType: generator
+metadata:
+  name: optimize_hyperparameters
+  description: Random walk to explore hyperparameter space
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example1-space.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example1-space.yaml
new file mode 100644
index 000000000..d7338dab9
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example1-space.yaml
@@ -0,0 +1,18 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: learning_rate
+    propertyDomain:
+      variableType: CONTINUOUS_VARIABLE_TYPE
+      domainRange: [0.001, 0.1]
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [16, 32, 64, 128]
+experiments:
+  - actuatorIdentifier: TrainerActuator
+    experimentIdentifier: train_model
+metadata:
+  name: hyperparameter_optimization
+  description: Optimize learning rate and batch size for model training
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example2-space.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example2-space.yaml
new file mode 100644
index 000000000..9cb7e6336
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example2-space.yaml
@@ -0,0 +1,20 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: learning_rate
+    propertyDomain:
+      variableType: CONTINUOUS_VARIABLE_TYPE
+      domainRange: [0.001, 0.1]
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [16, 32, 64]
+experiments:
+  - actuatorIdentifier: TrainerActuator
+    experimentIdentifier: train_model
+  - actuatorIdentifier: EvaluatorActuator
+    experimentIdentifier: evaluate_model
+metadata:
+  name: train_and_evaluate
+  description: Train models and evaluate on test set
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example3-space.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example3-space.yaml
new file mode 100644
index 000000000..8225d8932
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example3-space.yaml
@@ -0,0 +1,22 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: learning_rate
+    propertyDomain:
+      variableType: CONTINUOUS_VARIABLE_TYPE
+      domainRange: [0.001, 0.1]
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [32, 64] # Reduced for smaller space
+  - identifier: optimizer
+    propertyDomain:
+      variableType: CATEGORICAL_VARIABLE_TYPE
+      values: [adam, sgd, rmsprop]
+experiments:
+  - actuatorIdentifier: TrainerActuator
+    experimentIdentifier: train_model
+metadata:
+  name: optimizer_comparison
+  description: Compare optimizers with different learning rates
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example4-space.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example4-space.yaml
new file mode 100644
index 000000000..4f2642270
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example4-space.yaml
@@ -0,0 +1,22 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: learning_rate
+    propertyDomain:
+      variableType: CONTINUOUS_VARIABLE_TYPE
+      domainRange: [0.001, 0.1]
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [32, 64]
+experiments:
+  - actuatorIdentifier: TrainerActuator
+    experimentIdentifier: train_model
+    parameterization:
+      - property:
+          identifier: optimizer
+        value: adam
+metadata:
+  name: adam_optimization
+  description: Optimize learning rate with adam optimizer
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example5-space.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example5-space.yaml
new file mode 100644
index 000000000..96adeec2e
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example5-space.yaml
@@ -0,0 +1,18 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: learning_rate
+    propertyDomain:
+      variableType: CONTINUOUS_VARIABLE_TYPE
+      domainRange: [0.005, 0.02] # Narrowed around 0.01
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [32, 64]
+experiments:
+  - actuatorIdentifier: TrainerActuator
+    experimentIdentifier: train_model
+metadata:
+  name: fine_tune_lr
+  description: Fine-tune learning rate around 0.01
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example6-actuator-config.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example6-actuator-config.yaml
new file mode 100644
index 000000000..0b059f03b
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example6-actuator-config.yaml
@@ -0,0 +1,9 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+actuatorIdentifier: TrainerActuator
+parameters:
+  gpu_count: 2
+  gpu_type: A100
+metadata:
+  name: gpu_config
+  description: GPU configuration for training
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/example6-operation.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/example6-operation.yaml
new file mode 100644
index 000000000..61aa2ee2f
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/example6-operation.yaml
@@ -0,0 +1,14 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+spaces: [space-abc123]
+operation:
+  module:
+    operatorName: random_walk
+    operationType: search
+  parameters:
+    numberEntities: 50
+    batchSize: 1
+actuatorConfigurationIdentifiers: [actuatorconfiguration-xyz789]
+metadata:
+  name: gpu_random_walk
+  description: Random walk with GPU configuration
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-experiment-format.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-experiment-format.yaml
new file mode 100644
index 000000000..16d2850db
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-experiment-format.yaml
@@ -0,0 +1,9 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+experiments:
+  - actuatorIdentifier: actuator_id
+    experimentIdentifier: experiment_id
+    parameterization: # Optional - only if customizing optional properties
+      - property:
+          identifier: property_name
+        value: custom_value
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-operation-structure.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-operation-structure.yaml
new file mode 100644
index 000000000..7363af75a
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-operation-structure.yaml
@@ -0,0 +1,14 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+spaces: [space_id_1, space_id_2] # Required - list of space identifiers
+operation: # Required - operation definition
+  module: # Required - operator specification
+    operatorName: name # Required - operator identifier
+    operationType: type # Required - search/modify/characterize/etc.
+  parameters: # Required - operator-specific parameters
+    param1: value1
+    param2: value2
+actuatorConfigurationIdentifiers: [config_id_1] # Optional - actuator configs
+metadata: # Optional - operation metadata
+  name: operation_name
+  description: Description
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern1-simple-space.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern1-simple-space.yaml
new file mode 100644
index 000000000..08ad18983
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern1-simple-space.yaml
@@ -0,0 +1,11 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: learning_rate
+    propertyDomain:
+      variableType: CONTINUOUS_VARIABLE_TYPE
+      domainRange: [0.001, 0.1]
+experiments:
+  - actuatorIdentifier: trainer
+    experimentIdentifier: train_model
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern2-multiple-experiments.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern2-multiple-experiments.yaml
new file mode 100644
index 000000000..eb90542ff
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern2-multiple-experiments.yaml
@@ -0,0 +1,13 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default
+entitySpace:
+  - identifier: batch_size
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [16, 32, 64]
+experiments:
+  - actuatorIdentifier: trainer
+    experimentIdentifier: train_model # Measures: accuracy
+  - actuatorIdentifier: evaluator
+    experimentIdentifier: evaluate_model # Requires: accuracy (from train_model)
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern3-parameterized.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern3-parameterized.yaml
new file mode 100644
index 000000000..5ff81edb1
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern3-parameterized.yaml
@@ -0,0 +1,9 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+experiments:
+  - actuatorIdentifier: trainer
+    experimentIdentifier: train_model
+    parameterization:
+      - property:
+          identifier: optimizer
+        value: adam # Override default "sgd"
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern4-optional-property.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern4-optional-property.yaml
new file mode 100644
index 000000000..9f66d8c20
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-pattern4-optional-property.yaml
@@ -0,0 +1,11 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+entitySpace:
+  - identifier: batch_size # Required
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [16, 32, 64]
+  - identifier: optimizer # Optional - exploring different optimizers
+    propertyDomain:
+      variableType: CATEGORICAL_VARIABLE_TYPE
+      values: [adam, sgd, rmsprop]
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/reference-property-domain.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-property-domain.yaml
new file mode 100644
index 000000000..6eb3c2668
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/reference-property-domain.yaml
@@ -0,0 +1,8 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+identifier: property_name # Required - unique identifier
+propertyDomain: # Required - domain definition
+  variableType: DISCRETE_VARIABLE_TYPE | CONTINUOUS_VARIABLE_TYPE | CATEGORICAL_VARIABLE_TYPE | BINARY_VARIABLE_TYPE
+  domainRange: [min, max] # For discrete/continuous numeric
+  values: [val1, val2, '...'] # For discrete/categorical
+  interval: step_size # Optional - for discrete numeric
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/skill-manual-structure.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-manual-structure.yaml
new file mode 100644
index 000000000..d353abda1
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-manual-structure.yaml
@@ -0,0 +1,14 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+sampleStoreIdentifier: default # or existing store ID
+entitySpace:
+  - identifier: property_name
+    propertyDomain:
+      variableType: DISCRETE_VARIABLE_TYPE
+      values: [value1, value2, value3]
+experiments:
+  - actuatorIdentifier: actuator_name
+    experimentIdentifier: experiment_name
+metadata:
+  name: space_name
+  description: Description of the discovery space
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/skill-operation-structure.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-operation-structure.yaml
new file mode 100644
index 000000000..b4f60f4a8
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-operation-structure.yaml
@@ -0,0 +1,15 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+spaces:
+  - space_identifier # From Phase 1
+operation:
+  module:
+    operatorName: operator_name
+    operationType: search # or modify, characterize, etc.
+  parameters:
+    param1: value1
+    param2: value2
+actuatorConfigurationIdentifiers: [actuator_config_id] # Optional
+metadata:
+  name: operation_name
+  description: Description of the operation
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-continuous.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-continuous.yaml
new file mode 100644
index 000000000..abeceb82d
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-continuous.yaml
@@ -0,0 +1,5 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+propertyDomain:
+  variableType: CONTINUOUS_VARIABLE_TYPE
+  domainRange: [min, max]
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-categorical.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-categorical.yaml
new file mode 100644
index 000000000..cdaf8b694
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-categorical.yaml
@@ -0,0 +1,5 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+propertyDomain:
+  variableType: DISCRETE_VARIABLE_TYPE
+  values: [option1, option2, option3]
diff --git a/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-numeric.yaml b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-numeric.yaml
new file mode 100644
index 000000000..88bf7d0f2
--- /dev/null
+++ b/.cursor/skills/formulate-ado-problems/yaml-examples/skill-property-domain-discrete-numeric.yaml
@@ -0,0 +1,6 @@
+# Copyright (c) IBM Corporation
+# SPDX-License-Identifier: MIT
+propertyDomain:
+  variableType: DISCRETE_VARIABLE_TYPE
+  domainRange: [min, max]
+  values: [1, 2, 4, 8, 16]
diff --git a/.cursor/skills/query-ado-data/SKILL.md b/.cursor/skills/query-ado-data/SKILL.md
new file mode 100644
index 000000000..40dee8d90
--- /dev/null
+++ b/.cursor/skills/query-ado-data/SKILL.md
@@ -0,0 +1,296 @@
+---
+name: query-ado-data
+description: Query ado metadata and measurement data using CLI commands. Use when the user needs to find resources, filter by metadata, retrieve entities and measurements, or get resource schemas. Covers metastore queries (operations, discoveryspaces, samplestores, datacontainers, actuatorconfigurations) and samplestore queries (entities and measurements).
+---
+
+# Query ado Data
+
+ado stores data in two places:
+
+1. **Metastore**: Metadata about all resources (operations, discoveryspaces,
+samplestores, datacontainers, actuatorconfigurations)
+2. **Samplestores**: Entities and measurements made on them
+
+## Guidelines
+
+- When getting a list of resources the output will always be tabular formatted
+  string
+- Do not change context to answer a query unless specifically requested -
+  metadata and data is context specific
+
+### Fast Querying
+
+DOs:
+
+- IMPORTANT Before deciding on what to query check the resource schema to
+      confirm what is available in metadata
+      - ado template RESOURCETYPE --include-schema
+- Use Server side filtering
+     - prefer --query or --matching to fetching metadata and filtering on
+       client side
+- Fetch metadata over fetching data
+     - if a query can be answered via metadata it is much faster
+     - filter via metadata first if possible, before obtaining data
+     - IMPORTANT: ado show details space can be slow as it internally fetches
+       spaces data to calculate - prefer using metadata
+- Consider writing a script directly using SQLResourceStore API if the CLI
+  is not expressive enough BEFORE fetching data
+     - you can make batch requests e.g. getResources - much faster than
+       one-by-one requests
+
+DONTs
+
+- Do not fetch discoveryspace or operation data for summary queries
+  - Do not use: ado show entities, ado show requests, ado show results,
+    ado show details)
+  - Do not instantiating DiscoverySpace instances or SQLStore instance
+- Only use these commands or classes when drilling down on a narrow set of resources
+
+### Using Resource models
+
+Each resource has a pydantic model. If working in code you can use these models
+
+- discoveryspace, orchestrator/core/discoveryspace/resource.py:
+  DiscoverySpaceResource
+- samplestore, orchestrator/core/samplestore/resource.py:
+  SampleStoreResource
+- datacontainer, orchestrator/core/datacontainer/resource.py:
+  DataContainerResource
+- operation, orchestrator/core/operation/resource.py: OperationResource
+- actuatorconfiguraiton,
+  orchestrator/core/actuatorconfiguration/resource.py:
+  ActuatorConfigurationResource
+
+## Querying Metadata
+
+### Listing Resources
+
+Get a general overview of what's present:
+
+```bash
+uv run ado get $RESOURCETYPE --details
+```
+
+Returns an age-sorted list (most recent last) of resources of the specified type.
+
+**Resource types**: `operations` (`op`), `discoveryspaces` (`space`),
+`samplestores` (`store`), `datacontainers` (`dcr`), `actuatorconfigurations` (`ac`)
+
+### Filtering Resources
+
+Filter resources based on metadata fields using MySQL JSON Path queries:
+
+```bash
+uv run ado get $RESOURCETYPE --query 'path=candidate'
+```
+
+- Use single quotes around the candidate (required for strings, dictionaries, arrays)
+- Path is dot-separated (e.g., `config.metadata.labels`)
+- Candidate is a valid JSON value
+- Can specify `--query` multiple times (all filters must match)
+
+**Examples:**
+
+```bash
+# Find operations using a specific operator
+uv run ado get operations -q 'config.operation.module.moduleClass=RayTune'
+
+# Find spaces with a specific experiment
+uv run ado get spaces -q 'config.experiments={"experiments":{"identifier":"finetune-lora-fsdp-r-4-a-16-tm-default-v2.0.0"}}'
+
+# Combine multiple filters
+uv run ado get operations -q 'config.operation.parameters.batchSize=1' 
+-q 'status=[{"event": "finished", "exit_state": "success"}]'
+```
+
+For extensive examples, see `website/docs/resources/metastore.md`.
+
+### Filtering by Labels
+
+Filter resources by labels:
+
+```bash
+uv run ado get $RESOURCETYPE -l key=value
+```
+
+Can specify multiple times (all labels must match):
+
+```bash
+uv run ado get operations -l labelone=valueone -l label_two=value_two
+```
+
+### Matching Spaces
+
+Find spaces matching a point or another space:
+
+```bash
+# Match spaces containing a specific entity point
+uv run ado get space --matching-point point.yaml
+
+# Match spaces similar to another space (by ID)
+uv run ado get space --matching-space-id space-abc123-456def
+
+# Match spaces similar to a space configuration (without creating it)
+uv run ado get space --matching-space space.yaml
+```
+
+**Note**: `--matching-point`, `--matching-space`, and `--matching-space-id`
+are exclusive to spaces and override `--query` and `--label`.
+
+### Related Resources
+
+Get IDs of resources related to another resource (parent or child):
+
+```bash
+uv run ado show related $RESOURCETYPE [RESOURCE_ID] [--use-latest]
+```
+
+**Supported types**: `operation` (`op`), `samplestore` (`store`),
+`discoveryspace` (`space`)
+
+**Example:**
+
+```bash
+uv run ado show related space space-abc123-456def
+```
+
+### Get Resource Details
+
+View detailed information about a specific resource:
+
+```bash
+uv run ado show details $RESOURCETYPE [RESOURCE_ID] [--use-latest]
+```
+
+## Querying Data
+
+### Show Entities
+
+Get entities and their measurements from a space or operation:
+
+```bash
+uv run ado show entities $RESOURCETYPE [RESOURCE_ID] [--use-latest] \
+                  [--include {sampled | matching | missing | unsampled}] \
+                  [--property-format {observed | target}] \
+                  [--output-format {console | csv | json}] \
+                  [--property <property-name>] \
+                  [--aggregate {mean | median | variance | std | min | max}]
+```
+
+**Resource types**: `operation` (`op`), `discoveryspace` (`space`)
+
+**Key options:**
+
+- `--include` (spaces only): `sampled`, `unsampled`, `matching`, `missing`
+- `--property-format`: `observed` (one row per entity) or `target`
+(one row per entity-experiment pair)
+- `--output-format`: `console`, `csv`, or `json`
+- `--property`: Filter specific properties (can specify multiple times)
+- `--aggregate`: Aggregate multiple values
+
+**Examples:**
+
+```bash
+# Show matching entities in a space as CSV
+uv run ado show entities space space-abc123-456def --include matching \
+                                             --property-format target \
+                                             --output-format csv
+
+# Show entities from an operation with specific properties
+uv run ado show entities operation randomwalk-0.5.0-123abc \
+                  --property my-property-1 \
+                  --property my-property-2 \
+                  --output-format json
+```
+
+### Show Requests
+
+Get measurement requests sent during an operation:
+
+```bash
+uv run ado show requests operation [RESOURCE_ID] [--use-latest] \
+                            [--output-format {console | csv | json}] \
+                            [--hide <field>]
+```
+
+**Example:**
+
+```bash
+uv run ado show requests operation randomwalk-0.5.0-123abc -o csv
+```
+
+### Show Results
+
+Get measurement results metadata (valid/invalid status, etc.):
+
+```bash
+auv run do show results operation [RESOURCE_ID] [--use-latest] \
+                           [--output-format {console | csv | json}] \
+                           [--hide <field>]
+```
+
+**Note**: This shows metadata about results (validity, reasons for invalidity),
+not the actual measurement values.
+
+**Example:**
+
+```bash
+uv run ado show results operation randomwalk-0.5.0-123abc -o csv
+```
+
+## Getting Schemas
+
+Get JSON schemas for resource types:
+
+```bash
+uv run ado template $RESOURCETYPE --include-schema
+```
+
+**Example:**
+
+```bash
+# Get space template with schema
+uv run ado template space --include-schema
+
+# Get operation template with schema for a specific operator
+uv run ado template operation --operator-name OPERATOR_NAME --include-schema
+```
+
+## Common Patterns
+
+### Find operations that finished successfully
+
+```bash
+uv run ado get operations -q 'status=[{"event": "finished", "exit_state": "success"}]'
+```
+
+### Find spaces containing a specific model
+
+```bash
+uv run ado get spaces -q 'config.entitySpace={"propertyDomain":{"values":["mistral-7b-v0.1"]}}'
+```
+
+### Export operation entities to CSV
+
+```bash
+uv run ado show entities operation OPERATION_ID --output-format csv > entities.csv
+```
+
+### Get all resources related to a space
+
+```bash
+uv run ado show related space SPACE_ID
+```
+
+## Advanced Filtering
+
+The metastore class can provide more powerful querying via scripts.
+See orchestrator/metastore/sqlstore.py
+
+## References
+
+When modifying or creating code while using this skill, follow:
+
+- [general-development.mdc](../../rules/general-development.mdc)
+- [plugin-development.mdc](../../rules/plugin-development.mdc) (if working
+  with plugins)
diff --git a/pyproject.toml b/pyproject.toml
index 8aa7bb568..cdba561dc 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,6 +66,7 @@ dev = [
     "testcontainers>=4.10.0",
     "tox>=4.26.0",
     "tox-uv>=1.25.0",
+    "yamlfix>=1.19.1",
 ]
 docs = [
     "htmlmin>=0.1.12",
diff --git a/uv.lock b/uv.lock
index 4cb8389c3..5b2dccf8d 100644
--- a/uv.lock
+++ b/uv.lock
@@ -100,6 +100,7 @@ dev = [
     { name = "testcontainers" },
     { name = "tox" },
     { name = "tox-uv" },
+    { name = "yamlfix" },
 ]
 docs = [
     { name = "htmlmin" },
@@ -161,6 +162,7 @@ dev = [
     { name = "testcontainers", specifier = ">=4.10.0" },
     { name = "tox", specifier = ">=4.26.0" },
     { name = "tox-uv", specifier = ">=1.25.0" },
+    { name = "yamlfix", specifier = ">=1.19.1" },
 ]
 docs = [
     { name = "htmlmin", specifier = ">=0.1.12" },
@@ -211,10 +213,10 @@ requires-dist = [
 name = "ado-sfttrainer"
 source = { editable = "plugins/actuators/sfttrainer" }
 dependencies = [
-    { name = "aim" },
-    { name = "jwt" },
-    { name = "psutil" },
-    { name = "transformers" },
+    { name = "aim", marker = "python_full_version < '3.13'" },
+    { name = "jwt", marker = "python_full_version < '3.13'" },
+    { name = "psutil", marker = "python_full_version < '3.13'" },
+    { name = "transformers", marker = "python_full_version < '3.13'" },
 ]
 
 [package.metadata]
@@ -231,21 +233,17 @@ source = { editable = "plugins/actuators/vllm_performance" }
 dependencies = [
     { name = "ado-core" },
     { name = "datasets" },
-    { name = "huggingface-hub" },
+    { name = "guidellm" },
     { name = "kubernetes" },
-    { name = "numpy" },
-    { name = "transformers" },
     { name = "vllm" },
 ]
 
 [package.metadata]
 requires-dist = [
     { name = "ado-core" },
-    { name = "datasets" },
-    { name = "huggingface-hub" },
+    { name = "datasets", specifier = ">=2.20.0" },
+    { name = "guidellm", specifier = ">=0.5.3" },
     { name = "kubernetes", specifier = ">=31.0.0" },
-    { name = "numpy", specifier = ">=2" },
-    { name = "transformers", specifier = ">=4.45.0" },
     { name = "vllm", specifier = ">=0.12.0" },
 ]
 
@@ -261,31 +259,31 @@ name = "aim"
 version = "3.29.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "aim-ui" },
-    { name = "aimrecords" },
-    { name = "aimrocks" },
-    { name = "aiofiles" },
-    { name = "alembic" },
-    { name = "boto3" },
-    { name = "cachetools" },
-    { name = "click" },
-    { name = "cryptography" },
-    { name = "fastapi" },
-    { name = "filelock" },
-    { name = "jinja2" },
-    { name = "numpy" },
-    { name = "packaging" },
-    { name = "pillow" },
-    { name = "psutil" },
-    { name = "python-dateutil" },
-    { name = "pytz" },
-    { name = "requests" },
-    { name = "restrictedpython" },
-    { name = "sqlalchemy" },
-    { name = "tqdm" },
-    { name = "uvicorn" },
-    { name = "watchdog" },
-    { name = "websockets" },
+    { name = "aim-ui", marker = "python_full_version < '3.13'" },
+    { name = "aimrecords", marker = "python_full_version < '3.13'" },
+    { name = "aimrocks", marker = "python_full_version < '3.13'" },
+    { name = "aiofiles", marker = "python_full_version < '3.13'" },
+    { name = "alembic", marker = "python_full_version < '3.13'" },
+    { name = "boto3", marker = "python_full_version < '3.13'" },
+    { name = "cachetools", marker = "python_full_version < '3.13'" },
+    { name = "click", marker = "python_full_version < '3.13'" },
+    { name = "cryptography", marker = "python_full_version < '3.13'" },
+    { name = "fastapi", marker = "python_full_version < '3.13'" },
+    { name = "filelock", marker = "python_full_version < '3.13'" },
+    { name = "jinja2", marker = "python_full_version < '3.13'" },
+    { name = "numpy", marker = "python_full_version < '3.13'" },
+    { name = "packaging", marker = "python_full_version < '3.13'" },
+    { name = "pillow", marker = "python_full_version < '3.13'" },
+    { name = "psutil", marker = "python_full_version < '3.13'" },
+    { name = "python-dateutil", marker = "python_full_version < '3.13'" },
+    { name = "pytz", marker = "python_full_version < '3.13'" },
+    { name = "requests", marker = "python_full_version < '3.13'" },
+    { name = "restrictedpython", marker = "python_full_version < '3.13'" },
+    { name = "sqlalchemy", marker = "python_full_version < '3.13'" },
+    { name = "tqdm", marker = "python_full_version < '3.13'" },
+    { name = "uvicorn", marker = "python_full_version < '3.13'" },
+    { name = "watchdog", marker = "python_full_version < '3.13'" },
+    { name = "websockets", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/da/25/c825c73ec2f48c93324f631dba6e4cdac3bb60a7fde36e0b916820ae62a5/aim-3.29.1.tar.gz", hash = "sha256:30fb70f983844eebd270049206c839e6dc09ce9de500048dc97a7a8b22ed83fb", size = 1660733, upload-time = "2025-05-08T09:51:58.892Z" }
 wheels = [
@@ -315,7 +313,7 @@ name = "aimrecords"
 version = "0.0.7"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "base58" },
+    { name = "base58", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/c9/10/21182ef96acbd9a5ca4008556ba8590cbc1af833eccbf59d53308fa6d928/aimrecords-0.0.7.tar.gz", hash = "sha256:9b562fa5b5109b4b3dd4f83be0061cadbac63fa8031f281b8b5c8ae29967072f", size = 12667, upload-time = "2020-11-09T13:29:29.071Z" }
 wheels = [
@@ -465,6 +463,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/98/3b/40a68de458904bcc143622015fff2352b6461cd92fd66d3527bf1c6f5716/aiohttp_cors-0.8.1-py3-none-any.whl", hash = "sha256:3180cf304c5c712d626b9162b195b1db7ddf976a2a25172b35bb2448b890a80d", size = 25231, upload-time = "2025-03-31T14:16:18.478Z" },
 ]
 
+[[package]]
+name = "aiologic"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "sniffio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "wrapt" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a8/13/50b91a3ea6b030d280d2654be97c48b6ed81753a50286ee43c646ba36d3c/aiologic-0.16.0.tar.gz", hash = "sha256:c267ccbd3ff417ec93e78d28d4d577ccca115d5797cdbd16785a551d9658858f", size = 225952, upload-time = "2025-11-27T23:48:41.195Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f6/27/206615942005471499f6fbc36621582e24d0686f33c74b2d018fcfd4fe67/aiologic-0.16.0-py3-none-any.whl", hash = "sha256:e00ce5f68c5607c864d26aec99c0a33a83bdf8237aa7312ffbb96805af67d8b6", size = 135193, upload-time = "2025-11-27T23:48:40.099Z" },
+]
+
 [[package]]
 name = "aiosignal"
 version = "1.4.0"
@@ -483,10 +495,10 @@ name = "alembic"
 version = "1.18.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "mako" },
-    { name = "sqlalchemy" },
+    { name = "mako", marker = "python_full_version < '3.13'" },
+    { name = "sqlalchemy", marker = "python_full_version < '3.13'" },
     { name = "tomli", marker = "python_full_version < '3.11'" },
-    { name = "typing-extensions" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/49/cc/aca263693b2ece99fa99a09b6d092acb89973eb2bb575faef1777e04f8b4/alembic-1.18.1.tar.gz", hash = "sha256:83ac6b81359596816fb3b893099841a0862f2117b2963258e965d70dc62fb866", size = 2044319, upload-time = "2026-01-14T18:53:14.907Z" }
 wheels = [
@@ -1801,6 +1813,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cd/08/b5e3b9822662d72d540d830531e3ab6a7cabbda3dd56175696aabccfeb76/cuda_python-13.1.1-py3-none-any.whl", hash = "sha256:944cc4fe6482673d28dd545797a28840945a1668739328fa2ad1e9be4f7050d9", size = 8038, upload-time = "2025-12-09T22:13:10.719Z" },
 ]
 
+[[package]]
+name = "culsans"
+version = "0.10.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aiologic" },
+    { name = "typing-extensions", marker = "python_full_version < '3.12'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b7/4f/b2599d1e176653b73e51a6ac8a70faba7e41753ab42c36c30dc86780d638/culsans-0.10.0.tar.gz", hash = "sha256:76b8150ccb3ee2f62ac1209247414afbefe9f4020cef6c435c506cf166305ea0", size = 95105, upload-time = "2025-11-04T13:05:39.843Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/49/460759a919b9e921714608b4fd08ab9396c595abdd5245977b04c6119230/culsans-0.10.0-py3-none-any.whl", hash = "sha256:e832c9635ab7016cf62565de294269f4708cd92200d00dafdd2e5a1943587f2e", size = 14216, upload-time = "2025-11-04T13:05:38.757Z" },
+]
+
 [[package]]
 name = "cupy-cuda12x"
 version = "13.6.0"
@@ -1892,11 +1917,11 @@ wheels = [
 
 [[package]]
 name = "datasets"
-version = "2.14.4"
+version = "4.0.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "aiohttp" },
     { name = "dill" },
+    { name = "filelock" },
     { name = "fsspec", extra = ["http"] },
     { name = "huggingface-hub" },
     { name = "multiprocess" },
@@ -1909,9 +1934,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "xxhash" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/1d/69/8cc725b5d38968fd118e4ce56a483b16e75b7793854c1a392ec4a34eeb31/datasets-2.14.4.tar.gz", hash = "sha256:ef29c2b5841de488cd343cfc26ab979bff77efa4d2285af51f1ad7db5c46a83b", size = 2178719, upload-time = "2023-08-08T15:45:43.015Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/9d/348ed92110ba5f9b70b51ca1078d4809767a835aa2b7ce7e74ad2b98323d/datasets-4.0.0.tar.gz", hash = "sha256:9657e7140a9050db13443ba21cb5de185af8af944479b00e7ff1e00a61c8dbf1", size = 569566, upload-time = "2025-07-09T14:35:52.431Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/66/f8/38298237d18d4b6a8ee5dfe390e97bed5adb8e01ec6f9680c0ddf3066728/datasets-2.14.4-py3-none-any.whl", hash = "sha256:29336bd316a7d827ccd4da2236596279b20ca2ac78f64c04c9483da7cbc2459b", size = 519335, upload-time = "2023-08-08T15:45:38.837Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/62/eb8157afb21bd229c864521c1ab4fa8e9b4f1b06bafdd8c4668a7a31b5dd/datasets-4.0.0-py3-none-any.whl", hash = "sha256:7ef95e62025fd122882dbce6cb904c8cd3fbc829de6669a5eb939c77d50e203d", size = 494825, upload-time = "2025-07-09T14:35:50.658Z" },
 ]
 
 [[package]]
@@ -2088,6 +2113,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/de/15/545e2b6cf2e3be84bc1ed85613edd75b8aea69807a71c26f4ca6a9258e82/email_validator-2.3.0-py3-none-any.whl", hash = "sha256:80f13f623413e6b197ae73bb10bf4eb0908faf509ad8362c5edeb0be7fd450b4", size = 35604, upload-time = "2025-08-26T13:09:05.858Z" },
 ]
 
+[[package]]
+name = "eval-type-backport"
+version = "0.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fb/a3/cafafb4558fd638aadfe4121dc6cefb8d743368c085acb2f521df0f3d9d7/eval_type_backport-0.3.1.tar.gz", hash = "sha256:57e993f7b5b69d271e37482e62f74e76a0276c82490cf8e4f0dffeb6b332d5ed", size = 9445, upload-time = "2025-12-02T11:51:42.987Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cf/22/fdc2e30d43ff853720042fa15baa3e6122722be1a7950a98233ebb55cd71/eval_type_backport-0.3.1-py3-none-any.whl", hash = "sha256:279ab641905e9f11129f56a8a78f493518515b83402b860f6f06dd7c011fdfa8", size = 6063, upload-time = "2025-12-02T11:51:41.665Z" },
+]
+
 [[package]]
 name = "exceptiongroup"
 version = "1.3.1"
@@ -2118,6 +2152,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c1/ea/53f2148663b321f21b5a606bd5f191517cf40b7072c0497d3c92c4a13b1e/executing-2.2.1-py2.py3-none-any.whl", hash = "sha256:760643d3452b4d777d295bb167ccc74c64a81df23fb5e08eff250c425a4b2017", size = 28317, upload-time = "2025-09-01T09:48:08.5Z" },
 ]
 
+[[package]]
+name = "faker"
+version = "40.1.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5e/77/1c3ff07b6739b9a1d23ca01ec0a90a309a33b78e345a3eb52f9ce9240e36/faker-40.1.2.tar.gz", hash = "sha256:b76a68163aa5f171d260fc24827a8349bc1db672f6a665359e8d0095e8135d30", size = 1949802, upload-time = "2026-01-13T20:51:49.917Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/46/ec/91a434c8a53d40c3598966621dea9c50512bec6ce8e76fa1751015e74cef/faker-40.1.2-py3-none-any.whl", hash = "sha256:93503165c165d330260e4379fd6dc07c94da90c611ed3191a0174d2ab9966a42", size = 1985633, upload-time = "2026-01-13T20:51:47.982Z" },
+]
+
 [[package]]
 name = "fastai"
 version = "2.8.6"
@@ -2582,11 +2628,11 @@ wheels = [
 
 [[package]]
 name = "fsspec"
-version = "2026.1.0"
+version = "2025.3.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/d5/7d/5df2650c57d47c57232af5ef4b4fdbff182070421e405e0d62c6cdbfaa87/fsspec-2026.1.0.tar.gz", hash = "sha256:e987cb0496a0d81bba3a9d1cee62922fb395e7d4c3b575e57f547953334fe07b", size = 310496, upload-time = "2026-01-09T15:21:35.562Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/34/f4/5721faf47b8c499e776bc34c6a8fc17efdf7fdef0b00f398128bc5dcb4ac/fsspec-2025.3.0.tar.gz", hash = "sha256:a935fd1ea872591f2b5148907d103488fc523295e6c64b835cfad8c3eca44972", size = 298491, upload-time = "2025-03-07T21:47:56.461Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/01/c9/97cc5aae1648dcb851958a3ddf73ccd7dbe5650d95203ecb4d7720b4cdbf/fsspec-2026.1.0-py3-none-any.whl", hash = "sha256:cb76aa913c2285a3b49bdd5fc55b1d7c708d7208126b60f2eb8194fe1b4cbdcc", size = 201838, upload-time = "2026-01-09T15:21:34.041Z" },
+    { url = "https://files.pythonhosted.org/packages/56/53/eb690efa8513166adef3e0669afd31e95ffde69fb3c52ec2ac7223ed6018/fsspec-2025.3.0-py3-none-any.whl", hash = "sha256:efb87af3efa9103f94ca91a7f8cb7a4df91af9f74fc106c9c7ea0efd7277c1b3", size = 193615, upload-time = "2025-03-07T21:47:54.809Z" },
 ]
 
 [package.optional-dependencies]
@@ -2594,6 +2640,18 @@ http = [
     { name = "aiohttp" },
 ]
 
+[[package]]
+name = "ftfy"
+version = "6.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wcwidth" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a5/d3/8650919bc3c7c6e90ee3fa7fd618bf373cbbe55dff043bd67353dbb20cd8/ftfy-6.3.1.tar.gz", hash = "sha256:9b3c3d90f84fb267fe64d375a07b7f8912d817cf86009ae134aa03e1819506ec", size = 308927, upload-time = "2024-10-26T00:50:35.149Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ab/6e/81d47999aebc1b155f81eca4477a616a70f238a2549848c38983f3c22a82/ftfy-6.3.1-py3-none-any.whl", hash = "sha256:7c70eb532015cd2f9adb53f101fb6c7945988d023a085d127d1573dc49dd0083", size = 44821, upload-time = "2024-10-26T00:50:33.425Z" },
+]
+
 [[package]]
 name = "gguf"
 version = "0.17.1"
@@ -2770,6 +2828,37 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/32/af/6168cf4ff389deed1388b1196281c67cb36dbbf44aaee40e2bfb72ac0202/grpcio_reflection-1.76.0-py3-none-any.whl", hash = "sha256:d7c43f2047a2a9c9320a5905aa7133c677977436b5f63e6a868e507864a11c73", size = 22702, upload-time = "2025-10-21T16:27:40.846Z" },
 ]
 
+[[package]]
+name = "guidellm"
+version = "0.5.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "culsans" },
+    { name = "datasets" },
+    { name = "eval-type-backport" },
+    { name = "faker" },
+    { name = "ftfy" },
+    { name = "httpx", extra = ["http2"] },
+    { name = "loguru" },
+    { name = "msgpack" },
+    { name = "numpy" },
+    { name = "protobuf" },
+    { name = "pydantic" },
+    { name = "pydantic-settings" },
+    { name = "pyyaml" },
+    { name = "rich" },
+    { name = "sanic" },
+    { name = "tabulate" },
+    { name = "torch" },
+    { name = "transformers" },
+    { name = "uvloop" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/62/e4/55caa45ad29cf02bb006e1d83b7ae8be110a515b93030e180226b874d22c/guidellm-0.5.3.tar.gz", hash = "sha256:f58d6d46ad8d7df924ffafb410997d3f2763fbf7a6fc9f7a6b3f4c0a892b8132", size = 213008, upload-time = "2026-01-23T18:44:43.132Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/91/51e16c17e7821f55f43ca2758be05e6df2b897a47054215d608c5c20cbce/guidellm-0.5.3-py3-none-any.whl", hash = "sha256:ca84b9c433de0c8bb8427e818ccf45332a4bb7f2018308ebb3aebd595615357a", size = 248011, upload-time = "2026-01-23T18:44:40.615Z" },
+]
+
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -2779,6 +2868,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
 ]
 
+[[package]]
+name = "h2"
+version = "4.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "hpack" },
+    { name = "hyperframe" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1d/17/afa56379f94ad0fe8defd37d6eb3f89a25404ffc71d4d848893d270325fc/h2-4.3.0.tar.gz", hash = "sha256:6c59efe4323fa18b47a632221a1888bd7fde6249819beda254aeca909f221bf1", size = 2152026, upload-time = "2025-08-23T18:12:19.778Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/b2/119f6e6dcbd96f9069ce9a2665e0146588dc9f88f29549711853645e736a/h2-4.3.0-py3-none-any.whl", hash = "sha256:c438f029a25f7945c69e0ccf0fb951dc3f73a5f6412981daee861431b70e2bdd", size = 61779, upload-time = "2025-08-23T18:12:17.779Z" },
+]
+
 [[package]]
 name = "hf-xet"
 version = "1.2.0"
@@ -2801,6 +2903,24 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/44/870d44b30e1dcfb6a65932e3e1506c103a8a5aea9103c337e7a53180322c/hf_xet-1.2.0-cp37-abi3-win_amd64.whl", hash = "sha256:e6584a52253f72c9f52f9e549d5895ca7a471608495c4ecaa6cc73dba2b24d69", size = 2905735, upload-time = "2025-10-24T19:04:35.928Z" },
 ]
 
+[[package]]
+name = "hpack"
+version = "4.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2c/48/71de9ed269fdae9c8057e5a4c0aa7402e8bb16f2c6e90b3aa53327b113f8/hpack-4.1.0.tar.gz", hash = "sha256:ec5eca154f7056aa06f196a557655c5b009b382873ac8d1e66e79e87535f1dca", size = 51276, upload-time = "2025-01-22T21:44:58.347Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/07/c6/80c95b1b2b94682a72cbdbfb85b81ae2daffa4291fbfa1b1464502ede10d/hpack-4.1.0-py3-none-any.whl", hash = "sha256:157ac792668d995c657d93111f46b4535ed114f0c9c8d672271bbec7eae1b496", size = 34357, upload-time = "2025-01-22T21:44:56.92Z" },
+]
+
+[[package]]
+name = "html5tagger"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9e/02/2ae5f46d517a2c1d4a17f2b1e4834c2c7cc0fb3a69c92389172fa16ab389/html5tagger-1.3.0.tar.gz", hash = "sha256:84fa3dfb49e5c83b79bbd856ab7b1de8e2311c3bb46a8be925f119e3880a8da9", size = 14196, upload-time = "2023-03-28T05:59:34.642Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/12/2f5d43ee912ea14a6baba4b3db6d309b02d932e3b7074c3339b4aded98ff/html5tagger-1.3.0-py3-none-any.whl", hash = "sha256:ce14313515edffec8ed8a36c5890d023922641171b4e6e5774ad1a74998f5351", size = 10956, upload-time = "2023-03-28T05:59:32.524Z" },
+]
+
 [[package]]
 name = "htmlmin"
 version = "0.1.12"
@@ -2879,6 +2999,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
 ]
 
+[package.optional-dependencies]
+http2 = [
+    { name = "h2" },
+]
+
 [[package]]
 name = "httpx-sse"
 version = "0.4.3"
@@ -2907,6 +3032,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/bd/1a875e0d592d447cbc02805fd3fe0f497714d6a2583f59d14fa9ebad96eb/huggingface_hub-0.36.0-py3-none-any.whl", hash = "sha256:7bcc9ad17d5b3f07b57c78e79d527102d08313caa278a641993acddcb894548d", size = 566094, upload-time = "2025-10-23T12:11:59.557Z" },
 ]
 
+[[package]]
+name = "hyperframe"
+version = "6.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/02/e7/94f8232d4a74cc99514c13a9f995811485a6903d48e5d952771ef6322e30/hyperframe-6.1.0.tar.gz", hash = "sha256:f630908a00854a7adeabd6382b43923a4c4cd4b821fcb527e6ab9e15382a3b08", size = 26566, upload-time = "2025-01-22T21:41:49.302Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/48/30/47d0bf6072f7252e6521f3447ccfa40b421b6824517f82854703d0f5a98b/hyperframe-6.1.0-py3-none-any.whl", hash = "sha256:b03380493a519fce58ea5af42e4a42317bf9bd425596f7a0835ffce80f1a42e5", size = 13007, upload-time = "2025-01-22T21:41:47.295Z" },
+]
+
 [[package]]
 name = "identify"
 version = "2.6.16"
@@ -3534,7 +3668,7 @@ name = "jwt"
 version = "1.4.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "cryptography" },
+    { name = "cryptography", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/7f/20/21254c9e601e6c29445d1e8854c2a81bdb554e07a82fb1f9846137a6965c/jwt-1.4.0.tar.gz", hash = "sha256:f6f789128ac247142c79ee10f3dba6e366ec4e77c9920d18c1592e28aa0a7952", size = 24911, upload-time = "2025-06-23T13:28:38.289Z" }
 wheels = [
@@ -3737,12 +3871,28 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0c/29/0348de65b8cc732daa3e33e67806420b2ae89bdce2b04af740289c5c6c8c/loguru-0.7.3-py3-none-any.whl", hash = "sha256:31a33c10c8e1e10422bfd431aeb5d351c7cf7fa671e3c4df004162264b28220c", size = 61595, upload-time = "2024-12-06T11:20:54.538Z" },
 ]
 
+[[package]]
+name = "maison"
+version = "2.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "loguru" },
+    { name = "platformdirs" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+    { name = "typer" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/24/45/7cb1d08b6b5674c381b6e0232d35f417a1eba8bb66cdc18edff2b9c80b68/maison-2.0.2.tar.gz", hash = "sha256:476f2bf414a20f5abf5a9856bd4db78b5a33c695654a0fc49c3c4abed78c2efc", size = 16012, upload-time = "2025-10-09T07:52:33.27Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5b/8f/3f0895a18cad5afd61c16ac38d35a2466f0cac8ae5c28f1a67f7a81bcdec/maison-2.0.2-py3-none-any.whl", hash = "sha256:835de804aa8063795b48c4fe2b4918106cfda4e5df515e8784ec9fa64cd28191", size = 13464, upload-time = "2025-10-09T07:52:31.987Z" },
+]
+
 [[package]]
 name = "mako"
 version = "1.3.10"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "markupsafe" },
+    { name = "markupsafe", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/9e/38/bd5b78a920a64d708fe6bc8e0a2c075e1389d53bef8413725c63ba041535/mako-1.3.10.tar.gz", hash = "sha256:99579a6f39583fa7e5630a28c3c1f440e4e97a414b80372649c0ce338da2ea28", size = 392474, upload-time = "2025-04-10T12:44:31.16Z" }
 wheels = [
@@ -7035,6 +7185,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4d/e1/7348090988095e4e39560cfc2f7555b1b2a7357deba19167b600fdf5215d/ruff-0.14.13-py3-none-win_arm64.whl", hash = "sha256:7ab819e14f1ad9fe39f246cfcc435880ef7a9390d81a2b6ac7e01039083dd247", size = 13080224, upload-time = "2026-01-15T20:14:45.853Z" },
 ]
 
+[[package]]
+name = "ruyaml"
+version = "0.91.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "distro" },
+    { name = "setuptools" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4b/75/abbc7eab08bad7f47887a0555d3ac9e3947f89d2416678c08e025e449fdc/ruyaml-0.91.0.tar.gz", hash = "sha256:6ce9de9f4d082d696d3bde264664d1bcdca8f5a9dff9d1a1f1a127969ab871ab", size = 239075, upload-time = "2021-12-07T16:19:58.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/9a/16ca152a04b231c179c626de40af1d5d0bc2bc57bc875c397706016ddb2b/ruyaml-0.91.0-py3-none-any.whl", hash = "sha256:50e0ee3389c77ad340e209472e0effd41ae0275246df00cdad0a067532171755", size = 108906, upload-time = "2021-12-07T16:19:56.798Z" },
+]
+
 [[package]]
 name = "s3transfer"
 version = "0.16.0"
@@ -7073,6 +7236,37 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/58/5b/632a58724221ef03d78ab65062e82a1010e1bef8e8e0b9d7c6d7b8044841/safetensors-0.7.0-pp310-pypy310_pp73-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:473b32699f4200e69801bf5abf93f1a4ecd432a70984df164fc22ccf39c4a6f3", size = 531885, upload-time = "2025-11-19T15:18:27.146Z" },
 ]
 
+[[package]]
+name = "sanic"
+version = "25.12.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aiofiles" },
+    { name = "html5tagger" },
+    { name = "httptools" },
+    { name = "multidict" },
+    { name = "sanic-routing" },
+    { name = "setuptools" },
+    { name = "tracerite" },
+    { name = "typing-extensions" },
+    { name = "ujson", marker = "implementation_name == 'cpython' and sys_platform != 'win32'" },
+    { name = "uvloop", marker = "implementation_name == 'cpython' and sys_platform != 'win32'" },
+    { name = "websockets" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/69/f6/5e9ba853d2872119a252bff0cad712c015c1ed5318cceab5da68c7d2f1c4/sanic-25.12.0.tar.gz", hash = "sha256:ec124338f83a781da8095ed2676e60eb40c7fe21e7aa649a879f8860b4c7bd7a", size = 373452, upload-time = "2025-12-31T19:36:49.087Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9e/8a/16adaf66d358abfd0d24f2b76857196cf7effbf75c01306306bf39904e30/sanic-25.12.0-py3-none-any.whl", hash = "sha256:42ccf717f564aadab529a1522c489a709c4971c8123793ae07852aa110f8a913", size = 257787, upload-time = "2025-12-31T19:36:47.406Z" },
+]
+
+[[package]]
+name = "sanic-routing"
+version = "23.12.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d1/5c/2a7edd14fbccca3719a8d680951d4b25f986752c781c61ccf156a6d1ebff/sanic-routing-23.12.0.tar.gz", hash = "sha256:1dcadc62c443e48c852392dba03603f9862b6197fc4cba5bbefeb1ace0848b04", size = 29473, upload-time = "2023-12-31T09:28:36.992Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cf/e3/3425c9a8773807ac2c01d6a56c8521733f09b627e5827e733c5cd36b9ac5/sanic_routing-23.12.0-py3-none-any.whl", hash = "sha256:1558a72afcb9046ed3134a5edae02fc1552cff08f0fff2e8d5de0877ea43ed73", size = 25522, upload-time = "2023-12-31T09:28:35.233Z" },
+]
+
 [[package]]
 name = "scikit-learn"
 version = "1.7.2"
@@ -8076,6 +8270,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d0/30/dc54f88dd4a2b5dc8a0279bdd7270e735851848b762aeb1c1184ed1f6b14/tqdm-4.67.1-py3-none-any.whl", hash = "sha256:26445eca388f82e72884e0d580d5464cd801a3ea01e63e5601bdff9ba6a48de2", size = 78540, upload-time = "2024-11-24T20:12:19.698Z" },
 ]
 
+[[package]]
+name = "tracerite"
+version = "2.3.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "html5tagger" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/15/b9/89b065c1818e5973c333a33311f823954ff4c7c48440c20b37669c5b752c/tracerite-2.3.1.tar.gz", hash = "sha256:f46ee672d240d500a2331781b09eb33564d473f6ae60cd871ebce6c2413cffa8", size = 61303, upload-time = "2025-12-30T22:51:19.32Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b6/62/3f385a67ff3cc91209f107d20bbebdecf7a4e4aba55a43f9f71bddc424a9/tracerite-2.3.1-py3-none-any.whl", hash = "sha256:5f9595ba90f075b58e14a9baf84d8204fec3cdce50029f1c32d757af79d9ccbe", size = 65884, upload-time = "2025-12-30T22:51:18.1Z" },
+]
+
 [[package]]
 name = "traitlets"
 version = "5.14.3"
@@ -8188,6 +8394,41 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c7/b0/003792df09decd6849a5e39c28b513c06e84436a54440380862b5aeff25d/tzdata-2025.3-py2.py3-none-any.whl", hash = "sha256:06a47e5700f3081aab02b2e513160914ff0694bce9947d6b76ebd6bf57cfc5d1", size = 348521, upload-time = "2025-12-13T17:45:33.889Z" },
 ]
 
+[[package]]
+name = "ujson"
+version = "5.11.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/43/d9/3f17e3c5773fb4941c68d9a37a47b1a79c9649d6c56aefbed87cc409d18a/ujson-5.11.0.tar.gz", hash = "sha256:e204ae6f909f099ba6b6b942131cee359ddda2b6e4ea39c12eb8b991fe2010e0", size = 7156583, upload-time = "2025-08-20T11:57:02.452Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/21/1b/a4e7a41870797633423ea79618526747353fd7be9191f3acfbdee0bf264b/ujson-5.11.0-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3134b783ab314d2298d58cda7e47e7a0f7f71fc6ade6ac86d5dbeaf4b9770fa6", size = 57657, upload-time = "2025-08-20T11:55:05.169Z" },
+    { url = "https://files.pythonhosted.org/packages/94/ae/4e0d91b8f6db7c9b76423b3649612189506d5a06ddd3b6334b6d37f77a01/ujson-5.11.0-cp310-cp310-manylinux_2_24_i686.manylinux_2_28_i686.whl", hash = "sha256:185f93ebccffebc8baf8302c869fac70dd5dd78694f3b875d03a31b03b062cdb", size = 59780, upload-time = "2025-08-20T11:55:06.325Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/cc/46b124c2697ca2da7c65c4931ed3cb670646978157aa57a7a60f741c530f/ujson-5.11.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d06e87eded62ff0e5f5178c916337d2262fdbc03b31688142a3433eabb6511db", size = 57307, upload-time = "2025-08-20T11:55:07.493Z" },
+    { url = "https://files.pythonhosted.org/packages/39/eb/20dd1282bc85dede2f1c62c45b4040bc4c389c80a05983515ab99771bca7/ujson-5.11.0-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:181fb5b15703a8b9370b25345d2a1fd1359f0f18776b3643d24e13ed9c036d4c", size = 1036369, upload-time = "2025-08-20T11:55:09.192Z" },
+    { url = "https://files.pythonhosted.org/packages/64/a2/80072439065d493e3a4b1fbeec991724419a1b4c232e2d1147d257cac193/ujson-5.11.0-cp310-cp310-musllinux_1_2_i686.whl", hash = "sha256:a4df61a6df0a4a8eb5b9b1ffd673429811f50b235539dac586bb7e9e91994138", size = 1195738, upload-time = "2025-08-20T11:55:11.402Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/7e/d77f9e9c039d58299c350c978e086a804d1fceae4fd4a1cc6e8d0133f838/ujson-5.11.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:6eff24e1abd79e0ec6d7eae651dd675ddbc41f9e43e29ef81e16b421da896915", size = 1088718, upload-time = "2025-08-20T11:55:13.297Z" },
+    { url = "https://files.pythonhosted.org/packages/41/b8/ab67ec8c01b8a3721fd13e5cb9d85ab2a6066a3a5e9148d661a6870d6293/ujson-5.11.0-cp311-cp311-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:952c0be400229940248c0f5356514123d428cba1946af6fa2bbd7503395fef26", size = 57657, upload-time = "2025-08-20T11:55:21.296Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/c7/fb84f27cd80a2c7e2d3c6012367aecade0da936790429801803fa8d4bffc/ujson-5.11.0-cp311-cp311-manylinux_2_24_i686.manylinux_2_28_i686.whl", hash = "sha256:94fcae844f1e302f6f8095c5d1c45a2f0bfb928cccf9f1b99e3ace634b980a2a", size = 59779, upload-time = "2025-08-20T11:55:22.772Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/7c/48706f7c1e917ecb97ddcfb7b1d756040b86ed38290e28579d63bd3fcc48/ujson-5.11.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7e0ec1646db172beb8d3df4c32a9d78015e671d2000af548252769e33079d9a6", size = 57284, upload-time = "2025-08-20T11:55:24.01Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/ce/48877c6eb4afddfd6bd1db6be34456538c07ca2d6ed233d3f6c6efc2efe8/ujson-5.11.0-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:da473b23e3a54448b008d33f742bcd6d5fb2a897e42d1fc6e7bf306ea5d18b1b", size = 1036395, upload-time = "2025-08-20T11:55:25.725Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/7a/2c20dc97ad70cd7c31ad0596ba8e2cf8794d77191ba4d1e0bded69865477/ujson-5.11.0-cp311-cp311-musllinux_1_2_i686.whl", hash = "sha256:aa6b3d4f1c0d3f82930f4cbd7fe46d905a4a9205a7c13279789c1263faf06dba", size = 1195731, upload-time = "2025-08-20T11:55:27.915Z" },
+    { url = "https://files.pythonhosted.org/packages/15/f5/ca454f2f6a2c840394b6f162fff2801450803f4ff56c7af8ce37640b8a2a/ujson-5.11.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:4843f3ab4fe1cc596bb7e02228ef4c25d35b4bb0809d6a260852a4bfcab37ba3", size = 1088710, upload-time = "2025-08-20T11:55:29.426Z" },
+    { url = "https://files.pythonhosted.org/packages/03/3c/fd11a224f73fbffa299fb9644e425f38b38b30231f7923a088dd513aabb4/ujson-5.11.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0180a480a7d099082501cad1fe85252e4d4bf926b40960fb3d9e87a3a6fbbc80", size = 57600, upload-time = "2025-08-20T11:55:37.692Z" },
+    { url = "https://files.pythonhosted.org/packages/55/b9/405103cae24899df688a3431c776e00528bd4799e7d68820e7ebcf824f92/ujson-5.11.0-cp312-cp312-manylinux_2_24_i686.manylinux_2_28_i686.whl", hash = "sha256:fa79fdb47701942c2132a9dd2297a1a85941d966d8c87bfd9e29b0cf423f26cc", size = 59791, upload-time = "2025-08-20T11:55:38.877Z" },
+    { url = "https://files.pythonhosted.org/packages/17/7b/2dcbc2bbfdbf68f2368fb21ab0f6735e872290bb604c75f6e06b81edcb3f/ujson-5.11.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8254e858437c00f17cb72e7a644fc42dad0ebb21ea981b71df6e84b1072aaa7c", size = 57356, upload-time = "2025-08-20T11:55:40.036Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/71/fea2ca18986a366c750767b694430d5ded6b20b6985fddca72f74af38a4c/ujson-5.11.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:1aa8a2ab482f09f6c10fba37112af5f957689a79ea598399c85009f2f29898b5", size = 1036313, upload-time = "2025-08-20T11:55:41.408Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/bb/d4220bd7532eac6288d8115db51710fa2d7d271250797b0bfba9f1e755af/ujson-5.11.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:a638425d3c6eed0318df663df44480f4a40dc87cc7c6da44d221418312f6413b", size = 1195782, upload-time = "2025-08-20T11:55:43.357Z" },
+    { url = "https://files.pythonhosted.org/packages/80/47/226e540aa38878ce1194454385701d82df538ccb5ff8db2cf1641dde849a/ujson-5.11.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7e3cff632c1d78023b15f7e3a81c3745cd3f94c044d1e8fa8efbd6b161997bbc", size = 1088817, upload-time = "2025-08-20T11:55:45.262Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/c5/c161940967184de96f5cbbbcce45b562a4bf851d60f4c677704b1770136d/ujson-5.11.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78c684fb21255b9b90320ba7e199780f653e03f6c2528663768965f4126a5b50", size = 57603, upload-time = "2025-08-20T11:55:52.583Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/d6/c7b2444238f5b2e2d0e3dab300b9ddc3606e4b1f0e4bed5a48157cebc792/ujson-5.11.0-cp313-cp313-manylinux_2_24_i686.manylinux_2_28_i686.whl", hash = "sha256:4c9f5d6a27d035dd90a146f7761c2272cf7103de5127c9ab9c4cd39ea61e878a", size = 59794, upload-time = "2025-08-20T11:55:53.69Z" },
+    { url = "https://files.pythonhosted.org/packages/fe/a3/292551f936d3d02d9af148f53e1bc04306b00a7cf1fcbb86fa0d1c887242/ujson-5.11.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:837da4d27fed5fdc1b630bd18f519744b23a0b5ada1bbde1a36ba463f2900c03", size = 57363, upload-time = "2025-08-20T11:55:54.843Z" },
+    { url = "https://files.pythonhosted.org/packages/90/a6/82cfa70448831b1a9e73f882225980b5c689bf539ec6400b31656a60ea46/ujson-5.11.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:787aff4a84da301b7f3bac09bc696e2e5670df829c6f8ecf39916b4e7e24e701", size = 1036311, upload-time = "2025-08-20T11:55:56.197Z" },
+    { url = "https://files.pythonhosted.org/packages/84/5c/96e2266be50f21e9b27acaee8ca8f23ea0b85cb998c33d4f53147687839b/ujson-5.11.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:6dd703c3e86dc6f7044c5ac0b3ae079ed96bf297974598116aa5fb7f655c3a60", size = 1195783, upload-time = "2025-08-20T11:55:58.081Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/20/78abe3d808cf3bb3e76f71fca46cd208317bf461c905d79f0d26b9df20f1/ujson-5.11.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:3772e4fe6b0c1e025ba3c50841a0ca4786825a4894c8411bf8d3afe3a8061328", size = 1088822, upload-time = "2025-08-20T11:55:59.469Z" },
+    { url = "https://files.pythonhosted.org/packages/94/7e/0519ff7955aba581d1fe1fb1ca0e452471250455d182f686db5ac9e46119/ujson-5.11.0-pp311-pypy311_pp73-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:4b42c115c7c6012506e8168315150d1e3f76e7ba0f4f95616f4ee599a1372bbc", size = 50319, upload-time = "2025-08-20T11:56:51.63Z" },
+    { url = "https://files.pythonhosted.org/packages/74/cf/209d90506b7d6c5873f82c5a226d7aad1a1da153364e9ebf61eff0740c33/ujson-5.11.0-pp311-pypy311_pp73-manylinux_2_24_i686.manylinux_2_28_i686.whl", hash = "sha256:86baf341d90b566d61a394869ce77188cc8668f76d7bb2c311d77a00f4bdf844", size = 56584, upload-time = "2025-08-20T11:56:52.89Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/97/bd939bb76943cb0e1d2b692d7e68629f51c711ef60425fa5bb6968037ecd/ujson-5.11.0-pp311-pypy311_pp73-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4598bf3965fc1a936bd84034312bcbe00ba87880ef1ee33e33c1e88f2c398b49", size = 51588, upload-time = "2025-08-20T11:56:54.054Z" },
+]
+
 [[package]]
 name = "uri-template"
 version = "1.3.0"
@@ -8913,6 +9154,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7b/d9/8d95e906764a386a3d3b596f3c68bb63687dfca806373509f51ce8eea81f/xxhash-3.6.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:15e0dac10eb9309508bfc41f7f9deaa7755c69e35af835db9cb10751adebc35d", size = 31565, upload-time = "2025-10-02T14:37:06.966Z" },
 ]
 
+[[package]]
+name = "yamlfix"
+version = "1.19.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "maison" },
+    { name = "pydantic" },
+    { name = "ruyaml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/93/1d/b60d4411ff495de9b7598cc041e29c661e8e2f9d476a8a09bad1f54c1bce/yamlfix-1.19.1.tar.gz", hash = "sha256:05f6add13959637564f278e9237f6e201ff75e061a0a4cb9fc06fa95c3001a22", size = 39483, upload-time = "2025-12-18T09:57:23.179Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/30/c7/cba5941b7066f59dbddfe88bdc7154edbe5119bacb3814599997fbc2acac/yamlfix-1.19.1-py3-none-any.whl", hash = "sha256:b885fcf171a2eb59df83c219355bb17dd147675645e2756754372c0bd0b80ea5", size = 28393, upload-time = "2025-12-18T09:57:21.547Z" },
+]
+
 [[package]]
 name = "yarl"
 version = "1.22.0"

From 3cc3ddf24e3ab9bbf945e2142a2c2684ba958ebc Mon Sep 17 00:00:00 2001
From: michaelj <michaelj@ie.ibm.com>
Date: Fri, 30 Jan 2026 17:18:35 +0000
Subject: [PATCH 2/8] fix(build): remove stray package

---
 .cursor/rules/general-development.mdc |  2 +-
 pyproject.toml                        |  1 -
 uv.lock                               | 46 ---------------------------
 3 files changed, 1 insertion(+), 48 deletions(-)

diff --git a/.cursor/rules/general-development.mdc b/.cursor/rules/general-development.mdc
index 051f05771..a060456e6 100644
--- a/.cursor/rules/general-development.mdc
+++ b/.cursor/rules/general-development.mdc
@@ -100,7 +100,7 @@ Use Test Driven Development
 
 - Run **yamlfix** after YAML changes
 
-   uv run yamlfix $FILE
+   pre-commit run yamlfmt
 
 
 ---
diff --git a/pyproject.toml b/pyproject.toml
index cdba561dc..8aa7bb568 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,7 +66,6 @@ dev = [
     "testcontainers>=4.10.0",
     "tox>=4.26.0",
     "tox-uv>=1.25.0",
-    "yamlfix>=1.19.1",
 ]
 docs = [
     "htmlmin>=0.1.12",
diff --git a/uv.lock b/uv.lock
index 5b2dccf8d..ca850ee84 100644
--- a/uv.lock
+++ b/uv.lock
@@ -100,7 +100,6 @@ dev = [
     { name = "testcontainers" },
     { name = "tox" },
     { name = "tox-uv" },
-    { name = "yamlfix" },
 ]
 docs = [
     { name = "htmlmin" },
@@ -162,7 +161,6 @@ dev = [
     { name = "testcontainers", specifier = ">=4.10.0" },
     { name = "tox", specifier = ">=4.26.0" },
     { name = "tox-uv", specifier = ">=1.25.0" },
-    { name = "yamlfix", specifier = ">=1.19.1" },
 ]
 docs = [
     { name = "htmlmin", specifier = ">=0.1.12" },
@@ -3871,22 +3869,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0c/29/0348de65b8cc732daa3e33e67806420b2ae89bdce2b04af740289c5c6c8c/loguru-0.7.3-py3-none-any.whl", hash = "sha256:31a33c10c8e1e10422bfd431aeb5d351c7cf7fa671e3c4df004162264b28220c", size = 61595, upload-time = "2024-12-06T11:20:54.538Z" },
 ]
 
-[[package]]
-name = "maison"
-version = "2.0.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "loguru" },
-    { name = "platformdirs" },
-    { name = "tomli", marker = "python_full_version < '3.11'" },
-    { name = "typer" },
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/24/45/7cb1d08b6b5674c381b6e0232d35f417a1eba8bb66cdc18edff2b9c80b68/maison-2.0.2.tar.gz", hash = "sha256:476f2bf414a20f5abf5a9856bd4db78b5a33c695654a0fc49c3c4abed78c2efc", size = 16012, upload-time = "2025-10-09T07:52:33.27Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/5b/8f/3f0895a18cad5afd61c16ac38d35a2466f0cac8ae5c28f1a67f7a81bcdec/maison-2.0.2-py3-none-any.whl", hash = "sha256:835de804aa8063795b48c4fe2b4918106cfda4e5df515e8784ec9fa64cd28191", size = 13464, upload-time = "2025-10-09T07:52:31.987Z" },
-]
-
 [[package]]
 name = "mako"
 version = "1.3.10"
@@ -7185,19 +7167,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4d/e1/7348090988095e4e39560cfc2f7555b1b2a7357deba19167b600fdf5215d/ruff-0.14.13-py3-none-win_arm64.whl", hash = "sha256:7ab819e14f1ad9fe39f246cfcc435880ef7a9390d81a2b6ac7e01039083dd247", size = 13080224, upload-time = "2026-01-15T20:14:45.853Z" },
 ]
 
-[[package]]
-name = "ruyaml"
-version = "0.91.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "distro" },
-    { name = "setuptools" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/4b/75/abbc7eab08bad7f47887a0555d3ac9e3947f89d2416678c08e025e449fdc/ruyaml-0.91.0.tar.gz", hash = "sha256:6ce9de9f4d082d696d3bde264664d1bcdca8f5a9dff9d1a1f1a127969ab871ab", size = 239075, upload-time = "2021-12-07T16:19:58.427Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/1e/9a/16ca152a04b231c179c626de40af1d5d0bc2bc57bc875c397706016ddb2b/ruyaml-0.91.0-py3-none-any.whl", hash = "sha256:50e0ee3389c77ad340e209472e0effd41ae0275246df00cdad0a067532171755", size = 108906, upload-time = "2021-12-07T16:19:56.798Z" },
-]
-
 [[package]]
 name = "s3transfer"
 version = "0.16.0"
@@ -9154,21 +9123,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7b/d9/8d95e906764a386a3d3b596f3c68bb63687dfca806373509f51ce8eea81f/xxhash-3.6.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:15e0dac10eb9309508bfc41f7f9deaa7755c69e35af835db9cb10751adebc35d", size = 31565, upload-time = "2025-10-02T14:37:06.966Z" },
 ]
 
-[[package]]
-name = "yamlfix"
-version = "1.19.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "click" },
-    { name = "maison" },
-    { name = "pydantic" },
-    { name = "ruyaml" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/93/1d/b60d4411ff495de9b7598cc041e29c661e8e2f9d476a8a09bad1f54c1bce/yamlfix-1.19.1.tar.gz", hash = "sha256:05f6add13959637564f278e9237f6e201ff75e061a0a4cb9fc06fa95c3001a22", size = 39483, upload-time = "2025-12-18T09:57:23.179Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/30/c7/cba5941b7066f59dbddfe88bdc7154edbe5119bacb3814599997fbc2acac/yamlfix-1.19.1-py3-none-any.whl", hash = "sha256:b885fcf171a2eb59df83c219355bb17dd147675645e2756754372c0bd0b80ea5", size = 28393, upload-time = "2025-12-18T09:57:21.547Z" },
-]
-
 [[package]]
 name = "yarl"
 version = "1.22.0"

From 3667ba4be2b32c23697a66b2380c1be2d98a44ba Mon Sep 17 00:00:00 2001
From: michaelj <michaelj@ie.ibm.com>
Date: Fri, 30 Jan 2026 17:23:35 +0000
Subject: [PATCH 3/8] fix(agent): linting rules

---
 .cursor/rules/general-development.mdc | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/.cursor/rules/general-development.mdc b/.cursor/rules/general-development.mdc
index a060456e6..5baa1cccc 100644
--- a/.cursor/rules/general-development.mdc
+++ b/.cursor/rules/general-development.mdc
@@ -94,15 +94,14 @@ Use Test Driven Development
 
 - Fix any issues reported by ruff that it could not fix automatically.
 - Run black and ruff at directory level for efficiency (e.g. `orchestrator/`, `plugins/`, `tests/`).
-- Run the mkdocs linter only when creating or modifying documentation in the `website/` directory:
+- Run the mkdocs linter on markdown files (*.md) that have added or modified:
 
-    uv run markdownlint-cli2 NEW_OR_CHANGED_FILE --fix
+    uv run markdownlint-cli2 NEW_OR_CHANGED_MARKDOWN_FILE --fix
 
-- Run **yamlfix** after YAML changes
+- Run if YAML changed or added
 
    pre-commit run yamlfmt
 
-
 ---
 
 ## Code Testing
@@ -130,4 +129,4 @@ Use Test Driven Development
 
 ---
 
-- For plugin development, see [plugin-development.mdc](plugin-development.mdc)
\ No newline at end of file
+- For plugin development, see [plugin-development.mdc](plugin-development.mdc)

From a4ea04363e518c864cc3fe296ce11ed1bec12026 Mon Sep 17 00:00:00 2001
From: michaelj <michaelj@ie.ibm.com>
Date: Fri, 30 Jan 2026 17:23:48 +0000
Subject: [PATCH 4/8] fix(agent): lint

---
 .cursor/rules/plugin-development.mdc | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.cursor/rules/plugin-development.mdc b/.cursor/rules/plugin-development.mdc
index 0f4e44e8d..e3163b218 100644
--- a/.cursor/rules/plugin-development.mdc
+++ b/.cursor/rules/plugin-development.mdc
@@ -160,14 +160,19 @@ Before considering a plugin complete, verify:
 
 - [ ] **Experiment execution**: Use `run_experiment` tool to verify custom_experiment or actuator experiments can run successfully
 - [ ] **Valid DiscoverySpace YAML**: Create and validate a discoveryspace YAML that uses the experiment/actuator
+
   ```bash
   ado create discoveryspace -f space.yaml --dry-run
   ```
+
 - [ ] **Valid Operation YAML**: Create and validate an operation YAML that uses the operator
+
   ```bash
   ado create operation -f operation.yaml --dry-run
   ```
+
 - [ ] **Unit tests pass**: Run pytest on the plugin package
+
   ```bash
   uv run pytest plugins/your_plugin_type/your_plugin/tests/
   ```

From 531236b6370ef6522a821f127743538381c0529f Mon Sep 17 00:00:00 2001
From: michaelj <michaelj@ie.ibm.com>
Date: Fri, 30 Jan 2026 17:31:00 +0000
Subject: [PATCH 5/8] fix(agent): review fixes

---
 .cursor/commands/review.md             |  8 +++---
 .cursor/rules/general-development.mdc  | 36 ++++++++++++++++----------
 .cursor/skills/query-ado-data/SKILL.md |  4 +--
 3 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/.cursor/commands/review.md b/.cursor/commands/review.md
index 52271c8a9..4e39d4f13 100644
--- a/.cursor/commands/review.md
+++ b/.cursor/commands/review.md
@@ -6,10 +6,12 @@
 - Link comments to code
 - Format report with following sections (omit if not relevant)
   - Overview: What is changed
-  - Bugs:Any potential bugs
-  - Critical Issues: Critical problems with implementation or structure
+  - Bugs: Any potential bugs
+  - Critical Issues: Critical problems with implementation or
+    structure
   - Medium Issues: Issues that should be considered but may not need to be
     fixed now
   - Style Issues: Any style changes that should be made
-  - Linting Issues: Issues raised by the linters
+  - Linting Issues: Issues raised by the linters. black, ruff or
+    markdownlint-cli2 lints will block commits
 - Write review to md file also
diff --git a/.cursor/rules/general-development.mdc b/.cursor/rules/general-development.mdc
index 5baa1cccc..97ad9ae60 100644
--- a/.cursor/rules/general-development.mdc
+++ b/.cursor/rules/general-development.mdc
@@ -10,18 +10,23 @@ These guidelines apply to all code development in the ad-orchestrator codebase.
 ## Code Structure
 
 - **orchestrator**: main Python package
-  - **schema**: pydantic models for properties, entities, experiments, and measurement results
-  - **core**: pydantic models and associated code for the core resource types managed by ado:
+  - **schema**: pydantic models for properties, entities, experiments,
+    and measurement results
+  - **core**: pydantic models and associated code for the core resource
+    types managed by ado:
     - discoveryspace
     - operation
     - samplestore
     - datacontainer
     - actuatorconfiguration
-  - **modules/actuators**: defines actuators, custom experiments, and their associated management code (plugins, registry)
-  - **modules/operators**: defines operators and their associated management code (plugins, collections, orchestration)
+  - **modules/actuators**: defines actuators, custom experiments, and their
+    associated management code (plugins, registry)
+  - **modules/operators**: defines operators and their associated management
+    code (plugins, collections, orchestration)
   - **utilities**: common utilities
   - **cli**: ado CLI
-  - **metastore**: code defining and interacting with the metastore, which stores core resource types
+  - **metastore**: code defining and interacting with the metastore, which
+    stores core resource types
 - **tests**: unit and integration tests (pytest)
 - **plugins**: actuator, operator, and custom_experiment plugins
 - **website**: mkdocs website and documentation
@@ -38,23 +43,27 @@ These guidelines apply to all code development in the ad-orchestrator codebase.
 
 - Use PEP8 naming conventions for new code.
 - **Exception**: use camelCase for fields of pydantic models.
-- Do not modify existing names unless explicitly asked, even if they do not follow PEP8.
+- Do not modify existing names unless explicitly asked, even if they do not
+  follow PEP8.
 - Use type annotations on all functions and methods, including return types.
 - Add docstrings to all functions and methods.
 - Use the pydantic annotated form for pydantic fields
   (see `orchestrator/schema/entity.py`).
 - Use discriminated unions when a type is a union
   (see `ExperimentType` in `orchestrator/schema/experiment.py`).
-- Use the `Defaultable` type from `orchestrator/utilities/pydantic` for pydantic fields that:
+- Use the `Defaultable` type from `orchestrator/utilities/pydantic` for
+  pydantic fields that:
   - accept `None`, but
   - are always defaulted to a different type.
-- Use absolute imports within the repository unless the file already uses relative imports.
+- Use absolute imports within the repository unless the file already uses
+  relative imports.
 
 ---
 
 ## Developer Tools
 
-- All development tools (ruff, black, pytest, etc.) are available in the project’s **uv-managed virtual environment**.
+- All development tools (ruff, black, pytest, etc.) are available in the
+  project's **uv-managed virtual environment**.
 - Do not install tools globally.
 - Use the following pattern to execute tools:
 
@@ -86,21 +95,22 @@ Use Test Driven Development
 - Linting must be run after any code changes and must pass before running tests.
 - Run **black** after changes:
 
-   uv run black $DIR
+    uv run black $DIR
 
 - Run **ruff** after changes:
 
-   uv run ruff check --fix $DIR
+    uv run ruff check --fix $DIR
 
 - Fix any issues reported by ruff that it could not fix automatically.
-- Run black and ruff at directory level for efficiency (e.g. `orchestrator/`, `plugins/`, `tests/`).
+- Run black and ruff at directory level for efficiency (e.g. `orchestrator/`,
+  `plugins/`, `tests/`).
 - Run the mkdocs linter on markdown files (*.md) that have added or modified:
 
     uv run markdownlint-cli2 NEW_OR_CHANGED_MARKDOWN_FILE --fix
 
 - Run if YAML changed or added
 
-   pre-commit run yamlfmt
+    pre-commit run yamlfmt
 
 ---
 
diff --git a/.cursor/skills/query-ado-data/SKILL.md b/.cursor/skills/query-ado-data/SKILL.md
index 40dee8d90..3b292a287 100644
--- a/.cursor/skills/query-ado-data/SKILL.md
+++ b/.cursor/skills/query-ado-data/SKILL.md
@@ -57,7 +57,7 @@ Each resource has a pydantic model. If working in code you can use these models
 - datacontainer, orchestrator/core/datacontainer/resource.py:
   DataContainerResource
 - operation, orchestrator/core/operation/resource.py: OperationResource
-- actuatorconfiguraiton,
+- actuatorconfiguration,
   orchestrator/core/actuatorconfiguration/resource.py:
   ActuatorConfigurationResource
 
@@ -224,7 +224,7 @@ uv run ado show requests operation randomwalk-0.5.0-123abc -o csv
 Get measurement results metadata (valid/invalid status, etc.):
 
 ```bash
-auv run do show results operation [RESOURCE_ID] [--use-latest] \
+uv run ado show results operation [RESOURCE_ID] [--use-latest] \
                            [--output-format {console | csv | json}] \
                            [--hide <field>]
 ```

From ad59599fae8474d225e428af20ecea319b7c4ec6 Mon Sep 17 00:00:00 2001
From: Vassilis Vassiliadis <vassilis.vassiliadis@ibm.com>
Date: Wed, 4 Feb 2026 14:14:13 +0000
Subject: [PATCH 6/8] docs(skills): fix typo

Signed-off-by: Vassilis Vassiliadis <vassilis.vassiliadis@ibm.com>
---
 .cursor/skills/query-ado-data/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.cursor/skills/query-ado-data/SKILL.md b/.cursor/skills/query-ado-data/SKILL.md
index 3b292a287..11f1d703a 100644
--- a/.cursor/skills/query-ado-data/SKILL.md
+++ b/.cursor/skills/query-ado-data/SKILL.md
@@ -43,7 +43,7 @@ DONTs
 - Do not fetch discoveryspace or operation data for summary queries
   - Do not use: ado show entities, ado show requests, ado show results,
     ado show details)
-  - Do not instantiating DiscoverySpace instances or SQLStore instance
+  - Do not instantiate DiscoverySpace instances or SQLStore instance
 - Only use these commands or classes when drilling down on a narrow set of resources
 
 ### Using Resource models

From 0b4735eecd9403e3c36666a39eea4da79abe6cc7 Mon Sep 17 00:00:00 2001
From: Vassilis Vassiliadis <vassilis.vassiliadis@ibm.com>
Date: Thu, 5 Feb 2026 14:25:20 +0000
Subject: [PATCH 7/8] docs(plugin-development): explain package layout and
 pyproject rules

Signed-off-by: Vassilis Vassiliadis <vassilis.vassiliadis@ibm.com>
---
 .cursor/rules/plugin-development.mdc | 32 +++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/.cursor/rules/plugin-development.mdc b/.cursor/rules/plugin-development.mdc
index e3163b218..ddd614c81 100644
--- a/.cursor/rules/plugin-development.mdc
+++ b/.cursor/rules/plugin-development.mdc
@@ -8,7 +8,7 @@ alwaysApply: false
 
 These guidelines apply when developing plugins for ado.
 Plugins are developed under `plugins/` or `examples/` directories.
-All general development guidelines from `general-development.mdc` also apply.
+All general development guidelines from `general-development.mdc` apply to plugins too.
 
 ---
 
@@ -102,11 +102,37 @@ Operators and custom experiments use entry points in `pyproject.toml`:
 ado-ray-tune = "ado_ray_tune.operator_function"
 ```
 
-**Custom Experiment Example:**
+## Custom Experiment Example
+
+Define a custom experiment entry point in your `pyproject.toml`:
 
 ```toml
 [project.entry-points."ado.custom_experiments"]
-min_gpu_experiment = "autoconf.min_gpu_recommender"
+my_experiments = "my_experiment.experiments"
+```
+
+**Key points**:
+
+- The value of `[project.entry-points."ado.custom_experiments"]` **must**
+  reference the fully qualified module path containing your experiments.
+  In this example, `my_experiment.experiments`.
+- All custom experiment functions should be implemented and decorated
+  inside `my_experiment/experiments.py`.
+- Ensure the package is installed in the environment so the entry point can
+  be discovered at runtime.
+
+### Package Layout
+
+Your custom experiment should be implemented as a standard Python package with
+the following structure:
+
+```text
+my_custom_experiment/
+├── pyproject.toml         # Package configuration and entry points
+├── README.md              # Package documentation
+└── my_experiment/
+    ├── __init__.py        # Package initialization and exports
+    └── experiments.py     # Experiment definitions (decorated functions)
 ```
 
 ---

From e63154dca096ec58b28bb0f07455f50b110c4e6b Mon Sep 17 00:00:00 2001
From: Vassilis Vassiliadis <vassilis.vassiliadis@ibm.com>
Date: Thu, 5 Feb 2026 14:27:49 +0000
Subject: [PATCH 8/8] docs(plugin-development): rules for annotating functions
 with @custom_experiment

Signed-off-by: Vassilis Vassiliadis <vassilis.vassiliadis@ibm.com>
---
 .cursor/rules/plugin-development.mdc | 29 ++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/.cursor/rules/plugin-development.mdc b/.cursor/rules/plugin-development.mdc
index ddd614c81..5da6043a6 100644
--- a/.cursor/rules/plugin-development.mdc
+++ b/.cursor/rules/plugin-development.mdc
@@ -159,18 +159,43 @@ MyProperty = ConstitutiveProperty(...)
     },
     parameterization={},
 )
-def my_custom_experiment(entity, actuator, parameterization):
+def my_custom_experiment(
+    param1: type1, 
+    param2: type2, 
+    optional_param1: 
+    type3=the_default_value
+  ):
     # Implementation
     return results
 ```
 
 **Key Points:**
 
+When generating a custom experiment you MUST follow the following rules:
+
 - Specify all `required_properties` that the experiment needs
 - List any `optional_properties`
 - Define `output_property_identifiers` for measurement results
 - Include descriptive metadata
-- Function signature must match: `(entity, actuator, parameterization)`
+- Function signature must contain the parameters of your function
+  and must be consistent with the properties you defined in
+  required_properties and optional_properties
+- DO NOT manually validate parameters for which there is a 
+  ConstitutiveProperty definition
+- The field PropertyDomain.DomainRange is defined as 
+  `[lower bound inclusive, upper bound exclusive]`
+- The return value of the experiment function **must** be of type 
+  `dict[int | bool | float | str | list[int | bool | float | str]]`
+- DO NOT use arbitrary keys in the return value of the experiment function.
+- You MUST draw all keys of the return value of the experiment out of 
+  the `output_property_identifiers` array defined in the @custom_experiment 
+  annotation
+- Garbage collect any temporary files you generate.
+- DO NOT assume that files you create will persist after the call to the 
+  experiment terminates
+- If observed properties include files, their contents may be encoded
+  as strings and included in the returned dictionary. This is intended
+  for small files on the order of a few kilobytes
 
 ---