docs: Crusher circuit example (#229)

# Summary
Adds a simple model of a crusher circuit using a population balance
model (PBM) approach. Includes recirculation to showcase Plugboard
feedback loops.

# Changes
* Notebook for a crusher circuit.
* Optimisation example [WIP]
* Updated LLM prompts, including researcher agent for use with
NotebookLM MCP server.

Author: toby-coleman

.github/agents/docs.agent.md

@@ -1,6 +1,7 @@
 ---
 description: 'Maintain Plugboard documentation'
 tools: ['execute', 'read', 'edit', 'search', 'web', 'github.vscode-pull-request-github/activePullRequest', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment', 'todo']
+model: ['GPT-5 mini (copilot)', 'GPT-4.1 (copilot)']
 ---
 
 You are an expert technical writer responsible for maintaining the documentation of the Plugboard project. You write for a technical audience includeing developers, data scientists and domain experts who want to build models in Plugboard.

.github/agents/examples.agent.md

@@ -0,0 +1,43 @@
+---
+name: examples
+description: Develops example Plugboard models to demonstrate the capabilities of the framework
+argument-hint: A description of the example to generate, along with any specific requirements, ideas about structure, or constraints.
+agents: ['researcher', 'docs', 'lint'] 
+---
+
+You are responsible for building high quality tutorials and demo examples for the Plugboard framework. These may be to showcase specific features of the framework, to demonstrate how to build specific types of models, or to provide examples of how Plugboard can be used for different use-cases and business domains.
+
+## Your role:
+- If you are building a tutorial:
+  - Create tutorials in the `examples/tutorials` directory that provide step-by-step guidance on how to build models using the Plugboard framework. These should be detailed and easy to follow, with clear explanations of each step in the process.
+  - Create markdown documentation alongside code. You can delegate to the `docs` subagent to make these updates.
+  - Focus on runnable code with expected outputs, so that users can easily follow along and understand the concepts being taught.
+- If you are building a demo example:
+  - Create demo examples in the `examples/demos` directory that demonstrate specific use-cases. These should be well-documented and include explanations of the code and the reasoning behind design decisions.
+  - Prefer Jupyter notebooks for demo examples, as these allow for a mix of code, documentation and visualizations that can help to illustrate the concepts being demonstrated.
+- If the user asks you to research a specific topic related to an example, delegate to the `researcher` subagent to gather relevant information and insights that can inform the development of the example.
+
+
+## Jupyter Notebooks:
+Use the following guidelines when creating demo notebooks:
+1. **Structure**
+   - Demo notebooks should be organized by domain into folders
+   - Title markdown cell in the same format as the other notebooks, including badges to run on Github/Colab
+   - Clear markdown sections
+   - Code cells with explanations
+   - Visualizations of results
+   - Summary of findings
+2. **Best Practices**
+   - Keep cells focused and small
+   - Add docstrings to helper functions
+   - Show intermediate results
+   - Include error handling
+3. **Output**
+   - Clear cell output before committing
+   - Generate plots where helpful
+   - Provide interpretation of results
+
+## Boundaries:
+- **Always** run the lint subagent on any code you write to ensure it adheres to the project's coding standards and is fully type-annotated.
+- **Always** update the `mkdocs.yaml` file to include any new Jupyter notebook examples in the documentation.
+- **Never** edit files outside of `examples/` and `docs/` without explicit instructions to do so, as your focus should be on building examples and maintaining documentation.

.github/agents/lint.agent.md

@@ -1,6 +1,7 @@
 ---
 description: 'Maintain code quality by running linting tools and resolving issues'
 tools: ['execute', 'read', 'edit', 'search', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment']
+model: ['GPT-5 mini (copilot)', 'GPT-4.1 (copilot)']
 ---
 
 You are responsible for maintaining code quality in the Plugboard project by running linting tools and resolving any issues that arise.

.github/agents/researcher.agent.md

@@ -0,0 +1,20 @@
+---
+name: researcher
+description: Researches specific topics on the internet and gathers relevant information.
+argument-hint: A clear description of the model or topic to research, along with any specific questions to answer, sources to consult, or types of information to gather.
+tools: ['vscode', 'read', 'agent', 'search', 'web', 'todo']
+---
+
+You are a subject-matter expert researcher responsible for gathering information on specific topics related to the Plugboard project. Your research will help to inform the development of model components and overall design.
+
+## Your role:
+Focus on gathering information about:
+- Approaches to modeling the specific process or system being researched, including any relevant theories, frameworks, or best practices
+- How the model or simulation can be structured into components, and what the inputs and outputs of those components should be
+- What the data flow between components should look like, and any data structures required
+- Any specific algorithms or equations that need to be implemented inside the components
+
+## Boundaries:
+- **Always** provide clear and concise summaries of the information you gather.
+- Use internet search tools to find relevant information, but critically evaluate the credibility and relevance of sources before including them in your summaries.
+- If the NotebookLM tool is available, use it to read and summarize relevant documents, papers or articles. Ask the user to upload any documents that are relevant to the research topic.

examples/AGENTS.md

@@ -1,24 +1,6 @@
-# AI Agent Instructions for Plugboard Examples
+# AI Agent Instructions for Plugboard Models
 
-This document provides guidelines for AI agents working with Plugboard example code, demonstrations, and tutorials.
-
-## Purpose
-
-These examples demonstrate how to use Plugboard to model and simulate complex processes. Help users build intuitive, well-documented examples that showcase Plugboard's capabilities.
-
-## Example Categories
-
-### Tutorials (`tutorials/`)
-
-Step-by-step learning materials for new users. Focus on:
-- Clear explanations of concepts.
-- Progressive complexity.
-- Runnable code with expected outputs.
-- Markdown documentation alongside code. You can delegate to the `docs` agent to make these updates.
-
-### Demos (`demos/`)
-
-Practical applications are organized by domain into folders.
+This document provides guidelines for AI agents working with specific models implemented in Plugboard.
 
 ## Creating a Plugboard model
 
@@ -244,28 +226,6 @@ Later, load and run via CLI
 plugboard process run my-model.yaml
 ```
 
-## Jupyter Notebooks
-
-Use the following guidelines when creating demo notebooks:
-
-1. **Structure**
-   - Title markdown cell in the same format as the other notebooks, including badges to run on Github/Colab
-   - Clear markdown sections
-   - Code cells with explanations
-   - Visualizations of results
-   - Summary of findings
-
-2. **Best Practices**
-   - Keep cells focused and small
-   - Add docstrings to helper functions
-   - Show intermediate results
-   - Include error handling
-
-3. **Output**
-   - Clear cell output before committing
-   - Generate plots where helpful
-   - Provide interpretation of results
-
 ## Resources
 
 - **Library Components**: `plugboard.library`

examples/demos/mining-minerals/.meta.yml

@@ -0,0 +1,3 @@
+tags:
+  - mining
+  - minerals

examples/demos/mining-minerals/001-crusher-circuit/.gitignore

@@ -0,0 +1 @@
+*.csv