Support documentation

.github/agents/DocReviewAgent.agent.md

@@ -50,7 +50,8 @@ When reviewing, verify that each page belongs in the correct part of this struct
 
 Special attention:
 - Physics pages should remain asset-focused and end-user-oriented.
-- Intro, Solver, Network, and conceptual Control pages should remain conceptual rather than implementation-heavy.
+- Intro, Solver, and conceptual Control pages should remain conceptual rather than implementation-heavy.
+- The Network page combines conceptual connectivity with source-grounded structural depth (representation, ESDL construction, sub-network partitioning) in one page; it should not, however, restate asset-internal physics, controller dispatch, or solver equation-assembly mechanics owned by other specialist agents.
 - Developer Documentation should remain contributor-facing.
 - API reference should remain generated reference rather than narrative documentation.
 - Support should remain concise and actionable.
@@ -164,6 +165,25 @@ Flag the following as errors:
   correlations owned by ``PhysicsAssetDocAgent`` instead of cross-linking, or restating the
   conceptual solver pages.
 
+Intro-specific review rules
+---------------------------
+Treat intro documentation as four distinct page intents:
+
+1. Intro landing and orientation
+2. Scope and boundaries
+3. Audience and use cases
+4. Input/output and execution contract
+
+Flag the following as errors:
+- boundary pages restating detailed runtime execution steps,
+- audience pages restating detailed input/output contract material,
+- input/output pages omitting a concrete ESDL-to-result execution path,
+- intro pages that answer multiple intro intents without a clear separation,
+- an intro subpage repeating the same cross-link target across more than one navigation
+  section (for example, an audience's "first stop" link reappearing verbatim in a later
+  "where to continue"/"see also" list, or a navigation section silently dropping an audience
+  covered everywhere else on the page).
+
 Control-specific review rules
 -----------------------------
 Treat control documentation as four distinct documentation types:
@@ -183,6 +203,18 @@ 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.
 
+Network-specific review rules
+------------------------------
+Network documentation is a single consolidated page (``doc/network/network_main.rst``)
+covering connectivity/communication with the solver and controller together with
+topology/representation, ESDL construction, and sub-network partitioning.
+
+Flag the following as errors:
+- the network page drifting into bare API reference, re-deriving asset-internal physics
+  equations owned by ``PhysicsAssetDocAgent`` instead of cross-linking, restating controller
+  dispatch decisions owned by ``ControllerBehaviorDocAgent``, or restating solver
+  equation-assembly mechanics owned by ``SolverBehaviorDocAgent``.
+
 Completeness review by page type
 --------------------------------
 Review each page according to its type.

.github/agents/DocumentationCoordinator.agent.md

@@ -88,7 +88,7 @@ Classify each task into one of the following documentation types:
 - Intro documentation
 - Solver conceptual documentation
 - Solver behavior and physical impact
-- Network conceptual documentation
+- Network documentation
 - Physics asset documentation
 - User-facing control concepts
 - Controller behavior and physical impact
@@ -99,6 +99,27 @@ Classify each task into one of the following documentation types:
 - Support documentation
 - Navigation/index/toctree maintenance
 
+Intro documentation refinement
+-----------------------------
+Treat intro documentation as a single consolidated page intent, authored entirely in
+``doc/intro/intro_main.rst``. The page must cover, concisely and in this order:
+
+1. Overview — what OMOTES.SIMULATOR_CORE is.
+2. What It Does — scope and boundaries (what simulator-core includes and excludes).
+3. Why It Is Used — audience and use cases (who uses the package and what
+   decisions/questions it supports).
+4. Example — the concrete ESDL-to-result run contract, with a trimmed runnable code
+   example and a short walkthrough, cross-referencing ``README.md`` for the full example.
+5. Related Documentation — links to the adjacent sections.
+
+Intro decision rule
+-------------------
+Do not split intro content into multiple pages or sub-tasks. Keep the page short
+(mesido-style brevity: short prose sections, not a page per audience/topic). If a request
+would grow the page into a long, multi-topic essay, push the excess detail out via
+cross-links to the relevant Solver/Network/Physics/Control/Developer pages rather than
+adding a new intro subpage.
+
 Solver documentation refinement
 --------------------------------
 Treat solver documentation as two distinct types:
@@ -115,6 +136,31 @@ Treat solver documentation as two distinct types:
   solving that system changes the solved physical model, at a level of detail comparable to the
   physics asset pages (``doc/solver/solver_behavior.rst``)
 
+Network documentation refinement
+---------------------------------
+Treat network documentation as a single consolidated page intent, authored entirely in
+``doc/network/network_main.rst``. The page covers, in one place: connectivity and
+communication between assets and the solver/controller, how the network graph is
+represented (nodes, junctions, connection points), how it is constructed from ESDL
+connectivity, and how it is partitioned into sub-networks. Depth comparable to the
+physics asset pages is expected within this single page; do not split it into separate
+topology/construction/sub-network pages.
+
+Network assumptions/limitations linking policy
+----------------------------------------------
+When authoring or reviewing the ``Assumptions`` and ``Limitations`` sections in
+``doc/network/network_main.rst``:
+
+- Link only to pages that already exist in the repository, or pages that are explicitly
+  being created in the same coordinated task.
+- Prefer section-level links (labels/``:ref:``) when a corresponding assumptions or
+  limitations section exists in the target page.
+- Do not reference API root pages, generated package index pages, or fallback API trees
+  as the primary target for these sections.
+- If a required target page does not yet exist and is not in-scope to be created,
+  remove the link and keep the statement local rather than inventing a destination.
+- Treat unresolved links as a blocking validation failure.
+
 Control documentation refinement
 --------------------------------
 Treat control as four distinct documentation types:
@@ -151,7 +197,7 @@ Delegate work according to the following rules:
 - Solver behavior and physical impact
   Route to: ``SolverBehaviorDocAgent``
 
-- Network conceptual documentation
+- Network documentation
   Route to: ``SystemConceptDocAgent``
 
 - Physics asset documentation
@@ -198,6 +244,13 @@ If a solver-related request is ambiguous, classify by the primary question being
 When a request mixes both, split it into separate sub-tasks and assign them separately. Do not
 allow a single page to serve both purposes.
 
+Network decision rule
+----------------------
+Do not split network content into multiple pages or sub-tasks. Whether the request is about
+connectivity/communication with the solver and controller, or about graph
+structure/representation, ESDL construction, or sub-network partitioning, route it to
+``doc/network/network_main.rst``.
+
 Control decision rule
 ---------------------
 If a control-related request is ambiguous, classify by the primary question being answered:
@@ -324,6 +377,12 @@ Each delegated task must include:
 - validation criteria,
 - required cross-links where relevant.
 
+For network documentation tasks, also include explicit link-target constraints for
+``Assumptions`` and ``Limitations``:
+- permitted targets (existing conceptual pages or pages created in-task),
+- prohibited targets (API root/generated index/fallback API tree),
+- required handling when no valid target exists (keep text local, no fabricated links).
+
 Coordinator output format
 -------------------------
 For each request, produce a coordination plan containing:
@@ -364,8 +423,10 @@ Use these cues when classifying requests:
   tolerance", "pressure-drop closure", "physical impact of the solve"
   => Solver behavior and physical impact
 
-- "how is the network represented", "nodes", "connections", "communication"
-  => Network conceptual documentation
+- "how is the network represented", "communication between assets and solver/controller",
+  "network topology", "node/junction connectivity", "how is the network built from ESDL",
+  "sub-network partitioning", "connection points"
+  => Network documentation
 
 - "control behavior", "setpoint propagation", "operating logic", "what does control do"
   => User-facing control concepts
@@ -410,6 +471,7 @@ Prevent duplication across sections.
 
 In particular:
 - Solver, Network, and Control pages may describe system behavior conceptually, but should not repeat asset-level physics details already owned by ``PhysicsAssetDocAgent``.
+- The network page may describe topology, construction, and partitioning in detail, but should not repeat asset-level physics, controller dispatch decisions, or solver equation-assembly mechanics owned by other specialist agents.
 - Developer guide pages may describe extension workflows, but should not duplicate autogenerated API reference.
 - API reference pages must not contain long narrative explanations that belong in the developer guide.
 
@@ -455,7 +517,10 @@ After coordination and downstream edits:
 3. Verify that pages are routed to the correct audience.
 4. Verify that there is no major duplication between end-user docs, conceptual docs, developer guides, and API reference.
 5. Verify that navigation and cross-links are coherent.
-6. Route authored pages through ``DocReviewAgent`` where audience, scope, or duplication review is needed.
-7. Route structural and build checks through ``SphinxValidationAgent``.
-8. If warnings or errors occur, route fixes back to the responsible specialist agent.
-9. Do not consider the task complete if the documentation architecture is inconsistent, the toctree order is broken, pages are assigned to the wrong documentation type, or required review/validation steps remain unresolved.
+6. For ``doc/network/network_main.rst`` assumptions/limitations links, verify that every
+  link target exists (or is created in-task), resolves cleanly in Sphinx, and does not
+  point to API root/generated index pages.
+7. Route authored pages through ``DocReviewAgent`` where audience, scope, or duplication review is needed.
+8. Route structural and build checks through ``SphinxValidationAgent``.
+9. If warnings or errors occur, route fixes back to the responsible specialist agent.
+10. Do not consider the task complete if the documentation architecture is inconsistent, the toctree order is broken, pages are assigned to the wrong documentation type, required review/validation steps remain unresolved, or network assumptions/limitations links violate the link-target policy above.

.github/agents/SupportDocAgent.agent.md

@@ -52,21 +52,31 @@ Before writing, inspect the closest matching existing documentation page and pre
 
 1. Follow repository documentation style first, especially:
    - ``doc/index.rst``
-   - ``doc/support/support.rst`` (existing Support page; already references the issue
-     tracker, ``CONTRIBUTING.md``, and ``README.md``)
+   - ``doc/support/support.rst`` (existing Support page; already references the
+     ``user_feedback`` repository, this repository's own issue tracker, ``CONTRIBUTING.md``,
+     and ``README.md``)
    - ``CONTRIBUTING.md`` (repository root — branch/PR/review workflow, lint/type-check
      requirements, test coverage guideline)
    - ``README.md`` (repository root)
 
 2. Use repository context as the authority for support channels.
 
-Concrete support paths confirmed to exist in this repository:
-- the GitHub issue tracker,
+Concrete support paths confirmed to exist:
+- the `Project-OMOTES/user_feedback <https://github.com/Project-OMOTES/user_feedback>`_
+  repository's Discussions, "Q&A" category — for usage questions
+  (``https://github.com/Project-OMOTES/user_feedback/discussions/new?category=q-a``),
+- the same repository's Issues, using the ``bug_report.yml``/``feature_request.yml``
+  templates — for bug reports and feature requests; browse existing issues at
+  ``https://github.com/Project-OMOTES/user_feedback/issues`` before filing a new one,
+- this repository's own GitHub issue tracker — for development/code-level issues in
+  simulator-core itself, paired with ``CONTRIBUTING.md``,
 - ``CONTRIBUTING.md``,
 - ``README.md``.
 
-No ``.github/ISSUE_TEMPLATE/`` directory exists in this repository — do not reference or
-invent issue templates.
+No ``.github/ISSUE_TEMPLATE/`` directory exists in *this* repository (simulator-core) — do
+not invent templates here. Templates do exist in the external ``user_feedback`` repository
+(``bug_report.yml``, ``feature_request.yml``, ``question.yml``) and may be referenced by
+name/purpose since they are real, confirmed artifacts — do not fabricate others.
 
 Rules for source usage:
 - Do not invent support channels that are not present in the repository context.
@@ -104,7 +114,6 @@ A good support page should answer:
 - Is this a bug, a documentation issue, or a usage question?
 - What should I include in my report?
 - Where should I look first before opening an issue?
-- When should I consult developer docs instead?
 
 A support page should not:
 - become a developer onboarding page,
@@ -129,11 +138,10 @@ Section order
 Use the following section order for all sections that are present:
 
 1. Title
-2. When to use this page
-3. Support Paths
-4. What to include
-5. Before requesting support
-6. Related Documentation
+2. Support Paths
+3. What to include
+4. Before requesting support
+5. Related Documentation
 
 Optional sections:
 - ``Bug Reports``
@@ -147,13 +155,6 @@ Optional sections may be added only when they materially improve clarity.
 Section requirements
 --------------------
 
-When to use this page
-~~~~~~~~~~~~~~~~~~~~~
-Explain:
-- who this page is for,
-- which types of requests belong here,
-- when the reader should use other documentation instead.
-
 Support Paths
 ~~~~~~~~~~~~~
 Describe the practical support/reporting routes available in the repository context.

.github/agents/SystemConceptDocAgent.agent.md

@@ -72,8 +72,7 @@ Before writing, inspect the closest matching existing documentation page and pre
 
 1. Follow repository documentation style first, especially:
    - ``doc/index.rst``
-   - For Intro pages: ``doc/intro/intro_main.rst``, ``doc/intro/audience_and_use_cases.rst``,
-     ``doc/intro/package_scope.rst``, ``doc/intro/simulation_input_and_output.rst``
+   - For Intro pages: ``doc/intro/intro_main.rst`` (the single consolidated intro page)
    - For Solver pages: ``doc/solver/solver_main.rst``
    - For Network pages: ``doc/network/network_main.rst``
    - For Control pages: ``doc/controller/controller.rst``
@@ -143,11 +142,48 @@ Classify the page intent as follows:
   how the solver participates in timestep execution, convergence behavior, result interpretation, and the relation between solving and simulation progression
 
 - ``Network``:
-  how the network is represented conceptually, how assets and connectivity affect behavior, and how users should think about network-level interactions
+  how the network is represented conceptually and structurally — connectivity and
+  communication with the solver/controller, the graph representation (nodes, junctions,
+  connection points), how it is constructed from ESDL, and how it is partitioned into
+  sub-networks, in a single page
 
 - ``Control``:
   current control concepts, setpoint propagation, operating logic at a conceptual level, and the user-visible consequences of control actions
 
+Intro single-page rule
+----------------------
+Keep the entire Intro in one page, ``doc/intro/intro_main.rst``. Do not split it into
+subpages. The page must answer, in this order, as short prose/bullet sections:
+
+1. Overview — what OMOTES.SIMULATOR_CORE is.
+2. What It Does — scope boundaries (what is in scope and out of scope).
+3. Why It Is Used — audience and use cases (who uses the package and what
+   decisions/questions it supports).
+4. Example — one concrete ESDL-to-result path at a conceptual level (ESDL model ->
+   EsdlObject -> SimulationConfiguration -> SimulationManager.execute -> DataFrame), with a
+   trimmed runnable code example, cross-linking to ``README.md`` for the full example and to
+   existing architecture/reference documentation for deeper details.
+5. Related Documentation — links to adjacent sections.
+
+Do not list the same cross-link target in more than one navigation section. Keep the page
+concise (mesido-style brevity) rather than growing it into a long, multi-topic essay; push
+excess depth out via cross-links instead of adding new intro subpages.
+
+Network single-page rule
+-------------------------
+Keep the entire Network section in one page, ``doc/network/network_main.rst``. Do not split
+it into topology/construction/sub-network subpages. The page covers, in order: Overview
+(connectivity and communication with the solver/controller), Representation (a structural
+component/role table — for example ``Network``, ``BaseAsset``, ``Node``, ``Junction``,
+``HeatNetwork`` — grounded in source), Construction (how the graph is built from ESDL
+connectivity), Sub-network partitioning, Node connectivity rules (including a concise
+structural equation such as node mass-flow continuity where it clarifies a constraint),
+Assumptions, Limitations, and Implementation reference. The structural component table and
+construction/partitioning narrative are an explicit exception to the general "no
+class-by-class API walkthrough" rule below — they describe structural role, not full API
+detail, and must still cross-link to ``doc/physics`` and ``doc/reference`` rather than
+re-deriving asset physics, controller dispatch, or solver equation-assembly mechanics.
+
 Do not use this agent to document:
 - how to extend control classes as a contributor,
 - how to add a new asset in code,
@@ -185,7 +221,10 @@ Only include details that improve user understanding or interpretation.
 
 Section order
 -------------
-Use the following section order for all sections that are present:
+Use the following section order for all sections that are present, except where the
+``Intro single-page rule`` or ``Network single-page rule`` above specifies a different,
+page-specific order — those take precedence for ``doc/intro/intro_main.rst`` and
+``doc/network/network_main.rst`` respectively:
 
 1. Title
 2. Overview