Controller documentation

.github/agents/ControllerBehaviorDocAgent.agent.md

@@ -97,6 +97,11 @@ existing ``doc/controller/behavior`` page as the structural template.
    setpoints, and physical-impact claims. Anchor the network dispatch description in
    ``NetworkController.update_setpoints``.
 
+3. For updates scoped to ``doc/controller/controller_behavior.rst``, also consult:
+  ``doc/physics/ideal_heat_storage_physics.rst`` for fill-level and effective
+  charge/discharge-capability interpretation, and ``doc/physics/heat_pump_physics.rst`` for
+  water-to-water heat-pump terminology context.
+
 Rules for source usage:
 - Use repository sources only.
 - Ground every decision-logic and physical-impact claim in the actual implementation, not in
@@ -192,6 +197,12 @@ curtail consumers), plus heat-transfer conversion and the pressure-set asset sel
 For a component page, cover that component's local rule (for example deriving effective storage
 charge/discharge power from available volume, or applying a producer priority and factor).
 
+For the ``Dispatch Logic for Supply, Demand, and Storage`` section in
+``doc/controller/controller_behavior.rst``, explicitly explain how storage fill level affects
+effective charge and discharge capability, including why capability clips near empty/full bounds,
+and cross-link to ``doc/physics/ideal_heat_storage_physics.rst`` instead of re-deriving
+asset-internal physics.
+
 Give the governing relation in simplified engineering form where it clarifies the decision.
 
 Setpoints Produced
@@ -274,6 +285,9 @@ the shared style rules. In addition:
 - Prefer short paragraphs with direct interpretation of decisions and their consequences.
 - Avoid textbook density and implementation-oriented wording.
 - Avoid unnecessary bullets outside tables, assumptions, and limitations.
+- For ``doc/controller/controller_behavior.rst`` specifically, use
+  ``water-to-water heat-pump`` as the preferred term in place of
+  ``four-port heat pump`` or ``four-port heat-pump``.
 
 reStructuredText requirements
 -----------------------------
@@ -305,13 +319,16 @@ After writing or updating a behavior page:
    existing ``doc/controller`` pages.
 5. Verify that decision-logic and physical-impact claims are supported by the source files in
    the source-priority table.
-6. Verify the page is toctreed only from ``doc/controller/controller.rst`` and not duplicated in
+6. For ``doc/controller/controller_behavior.rst``, verify terminology uses
+  ``water-to-water heat-pump`` and that storage-dispatch explanations include fill-level impact
+  and clipping context with a physics cross-link.
+7. Verify the page is toctreed only from ``doc/controller/controller.rst`` and not duplicated in
    any ``doc/reference/`` page.
-7. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the
+8. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the
    repository-preferred documentation build command.
-8. Inspect the build output for warnings and errors related to the new or edited page,
+9. Inspect the build output for warnings and errors related to the new or edited page,
    including rst syntax errors, malformed tables, invalid math blocks, broken references, and
    broken toctrees.
-9. If an error or warning is found, fix it before returning the final content.
-10. Do not finish with known syntax errors, broken section structure, malformed tables, broken
+10. If an error or warning is found, fix it before returning the final content.
+11. Do not finish with known syntax errors, broken section structure, malformed tables, broken
     math blocks, or unresolved build warnings caused by the change.

.github/agents/DocReviewAgent.agent.md

@@ -183,6 +183,14 @@ Flag the following as errors:
 - contributor control guides drifting into end-user explanation as their primary purpose,
 - controller API reference pages containing long narrative explanation better suited for conceptual docs or developer guides.
 
+For reviews of ``doc/controller/controller_behavior.rst``, also flag as errors:
+- use of ``four-port heat pump`` or ``four-port heat-pump`` where
+  ``water-to-water heat-pump`` terminology is required,
+- missing explanation in ``Dispatch Logic for Supply, Demand, and Storage`` of how fill level
+  constrains effective storage charge/discharge capability and clipping near empty/full bounds,
+- missing cross-link to ``doc/physics/ideal_heat_storage_physics.rst`` when storage fill-level
+  interpretation is discussed.
+
 Completeness review by page type
 --------------------------------
 Review each page according to its type.
@@ -270,6 +278,11 @@ Before accepting a page, verify that:
 - it links to the right neighboring documentation where useful,
 - it does not blur the boundary between conceptual docs, physics docs, developer guides, API reference, navigation, and support.
 
+For ``doc/controller/controller_behavior.rst`` specifically, also verify:
+- terminology uses ``water-to-water heat-pump`` consistently,
+- storage dispatch explanation includes fill-level impact and clipping behavior,
+- storage fill-level interpretation links to ``doc/physics/ideal_heat_storage_physics.rst``.
+
 Validation
 ----------
 After review and any focused edits:

.github/agents/DocumentationCoordinator.agent.md

@@ -217,6 +217,9 @@ If a control-related request is ambiguous, classify by the primary question bein
 When a request mixes more than one of these, split it into multiple sub-tasks and assign them separately.
 Do not allow a single page to serve all three purposes.
 
+If the user explicitly scopes a request to ``doc/controller/controller_behavior.rst`` only,
+keep scope locked to that single page unless the user asks to broaden scope.
+
 Audience separation rules
 -------------------------
 Enforce the following audience boundaries:
@@ -296,6 +299,14 @@ When delegating to a specialist agent, always specify:
 - validation criteria,
 - required cross-links to adjacent sections where relevant.
 
+For tasks scoped to ``doc/controller/controller_behavior.rst``, also specify:
+- terminology requirement: use ``water-to-water heat-pump`` wording,
+- completeness requirement: in the ``Dispatch Logic for Supply, Demand, and Storage`` section,
+  explain storage fill-level impact on effective charge/discharge capability and clipping near
+  empty/full bounds,
+- physics link requirement: include a cross-link to
+  ``doc/physics/ideal_heat_storage_physics.rst`` for asset-internal storage behavior.
+
 The coordinator must not delegate vague requests such as:
 - "write the docs"
 - "improve this page"
@@ -324,6 +335,9 @@ Each delegated task must include:
 - validation criteria,
 - required cross-links where relevant.
 
+For control-behavior tasks scoped to ``doc/controller/controller_behavior.rst``, add explicit
+exclusions preventing edits to other pages unless the user requests broader scope.
+
 Coordinator output format
 -------------------------
 For each request, produce a coordination plan containing:

.github/agents/SystemConceptDocAgent.agent.md

@@ -77,6 +77,7 @@ Before writing, inspect the closest matching existing documentation page and pre
    - For Solver pages: ``doc/solver/solver_main.rst``
    - For Network pages: ``doc/network/network_main.rst``
    - For Control pages: ``doc/controller/controller.rst``
+  - For Control behavioral terminology/context only: ``doc/controller/controller_behavior.rst``
    - ``doc/physics/physics_main.rst`` (cross-reference landing page only, not a style source for Physics content itself)
    - ``doc/architecture/architecture.rst``
    - any existing landing page in the same section as ``<TARGET_FILE>``
@@ -146,7 +147,10 @@ Classify the page intent as follows:
   how the network is represented conceptually, how assets and connectivity affect behavior, and how users should think about network-level interactions
 
 - ``Control``:
-  current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions
+  current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions.
+  Keep descriptions tied to the heat-network physics interface: controller output should be framed as
+  requested heat extraction/injection and boundary-condition intent that is later realized or constrained
+  by the hydraulic and thermal solve.
 
 Do not use this agent to document:
 - how to extend control classes as a contributor,
@@ -205,6 +209,8 @@ Optional sections:
 
 Optional sections may be added only when they materially improve clarity.
 
+**For ``Control`` pages specifically:** Omit the ``Limitations`` section. Control pages should end with ``Assumptions`` before proceeding to ``Related Documentation`` or the toctree.
+
 Section requirements
 --------------------
 
@@ -215,6 +221,10 @@ Explain:
 - why it matters,
 - how readers should think about it.
 
+For ``Control`` pages, phrase overview text in terms of physics-facing setpoint intent (for example,
+asset-level heat extraction/injection requests and pressure-boundary intent for the timestep solve),
+not only generic demand-profile propagation wording.
+
 For ``Intro`` pages, explicitly include:
 - what OMOTES.SIMULATOR_CORE does,
 - why it is used in practice.
@@ -244,6 +254,37 @@ Examples:
 
 Keep definitions concise and simulation-oriented.
 
+For ``Control`` pages, format each concept as a reStructuredText definition list:
+
+  **Concept Name**
+      Definition text here. For multi-line definitions, continue text on the next line with consistent indentation (same indent level as the first line of the definition).
+
+**IMPORTANT for reStructuredText formatting:** To prevent text from being boxed as literal blocks:
+  - Do NOT use extra indentation or line breaks that create gaps in the definition text.
+  - Do NOT use ``::`` or ``|`` markers within definitions.
+  - Write multi-line definitions as flowing text with uniform indentation, not as separate paragraphs or code blocks.
+  - Example of CORRECT formatting:
+
+    **Storages**
+        Flexible control components that can absorb or release heat. In the current model this includes ideal heat storage and ATES-based storage. Effective charge and discharge capability depends on current fill level or state of charge, which affects how much storage can contribute in a timestep.
+
+  - Example of INCORRECT formatting (will create a box):
+
+    **Storages**
+        Flexible control components that can absorb or release heat. In the current model this includes
+      ideal heat storage and ATES-based storage. Effective charge and discharge capability depends on
+      current fill level or state of charge, which affects how much storage can contribute in a timestep.
+
+Include at least these concepts when relevant to the current model:
+- Network Controller: the top-level control component that coordinates subnetworks
+- Subnetworks: hydraulically separated groups of assets
+- Consumers: demand-side components
+- Producers: supply-side components
+- Storages: flexible components with effective charge/discharge capability tied to fill level or state of charge
+- Heat-transfer assets: coupling components between subnetworks
+- Setpoints: asset-level control targets
+- Priority: dispatch ordering used when producer output must be capped; determines which producer supplies heat under surplus conditions
+
 Behavior and Interpretation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Describe the main behavior in practical terms.
@@ -268,12 +309,8 @@ Include only assumptions that matter for:
 - model setup,
 - understanding the documented workflow.
 
-Limitations
-~~~~~~~~~~~
-Use short bullets.
-
-State what the page intentionally simplifies or does not cover.
-Point readers to more specific sections when relevant.
+For ``Control`` pages, state that storage behavior is constrained by effective charging/discharging
+capability and that this capability depends on the current fill level/state of charge.
 
 Related Documentation
 ~~~~~~~~~~~~~~~~~~~~~
@@ -320,6 +357,14 @@ See [Documentation Architecture](../instructions/documentation-architecture.inst
 - Avoid implementation-oriented wording unless needed to anchor behavior.
 - Avoid unnecessary bullets outside assumptions, limitations, and short checklists.
 
+For ``Control`` page Key Concepts specifically:
+- Each concept must be formatted as a definition-list entry (bold concept name followed by indented definition).
+- Do not use code blocks, boxed elements, or literal formatting for concept definitions.
+- Do not use ``::`` or ``|`` markers within definition text.
+- Keep each definition to 1–2 concise sentences.
+- Do not nest concepts within examples or use numbered/bulleted lists within concept definitions.
+- For multi-line definitions, maintain consistent indentation across all lines to prevent reStructuredText from treating the text as a literal block (which would create a box).
+
 reStructuredText requirements
 -----------------------------
 See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared output-format requirements. In addition:
@@ -349,4 +394,11 @@ After writing or updating the file:
 7. Check that the page introduces no documentation build warnings or errors.
 8. If command execution or validation tools are available, run ``doc/run_spinx.bat`` or the repository-preferred documentation build command.
 9. If an error or warning is found, fix it before returning the final content.
-10. Do not finish with known syntax errors, broken headings, malformed math blocks, broken references, or unresolved build warnings caused by the change.
+10. Do not finish with known syntax errors, broken headings, malformed math blocks, broken references, or unresolved build warnings caused by the change.
+
+For ``Control`` pages specifically, also verify:
+- All required concepts (Network Controller, Subnetworks, Consumers, Producers, Storages, Heat-transfer assets, Setpoints, Priority) are present in the Key Concepts section.
+- Priority concept is clearly defined as related to dispatch ordering when producer output is capped.
+- No ``Limitations`` section is present; the page proceeds directly from ``Assumptions`` to ``Related Documentation``.
+- All Key Concept definitions are formatted as definition-list entries (bold name, indented definition) with no code blocks or boxes.
+- Specifically verify that the Storages concept definition does NOT appear in a box; its text should flow naturally as a continuation of the definition line.

.github/workflows/documentation.yml

@@ -0,0 +1,36 @@
+name: "Sphinx: Render docs"
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r doc/requirements.txt
+          pip install -e .
+      - name: Build HTML
+        run: |
+          cd doc
+          make html
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: doc/_build/html/
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: doc/_build/html