Refactor with architecture and developer documentation

.github/instructions/cpp-refactoring.instructions.md

@@ -0,0 +1,41 @@
+---
+description: "Use when moving, renaming, or refactoring C++ classes in src/. Covers include order, git mv, shared_ptr vs raw pointer, and C++ covariance rules."
+applyTo: "src/**/*.cpp,src/**/*.hpp,src/**/CMakeLists.txt"
+---
+
+# C++ Refactoring Guidelines
+
+## Include Order
+
+Within every `.cpp` and `.hpp`, includes must appear in this order, with a blank line between each group:
+
+```cpp
+// 1. Own header (in .cpp only — the header this .cpp implements)
+#include "ThisClass.hpp"
+
+// 2. Same-directory relative includes
+#include "Sibling.hpp"
+
+// 3. Cross-directory repo includes
+#include "../other_module/Foo.hpp"
+
+// 4. OpenStudio SDK includes
+#include <openstudio/model/Model.hpp>
+
+// 5. Qt, Boost, and system includes
+#include <QWidget>
+#include <boost/optional.hpp>
+#include <memory>
+```
+
+Do not mix groups. When adding a new include, place it in the correct group in the same edit — not as a deferred cleanup.  Within each group, sort includes alphabetically by filename.
+
+---
+
+## Naming
+
+When introducing an interface method, choose its name before writing any code:
+
+- Prefer names that describe the *concept*, not the return type (`currentDocument`, not `currentBaseDocument`).
+- Check for name collisions with existing virtuals in the inheritance chain before committing.
+- A rename that touches 100+ files is expensive; settle the name at design time.

.github/instructions/pr-review.instructions.md

@@ -0,0 +1,18 @@
+---
+description: "Use when reviewing pull requests, conducting code review, or checking a diff for correctness. Covers documentation accuracy checks for developer/doc/."
+---
+
+# Pull Request Review Guidelines
+
+On every PR review, verify documentation and comments are consistent with the code changes:
+
+**`developer/doc/` docs**
+- `CMakeLists.txt` changed → check the corresponding `libraries/*.md` for stale dependency tables or target names; check `architecture.md` dependency graph.
+- Class added/moved/deleted → check library doc's Key Classes section is accurate and the header has a `/** */` doc comment.
+
+**Inline comments**
+- Significant class added or refactored (`src/**/*.hpp`) → `/** */` comment above the class must exist, describe current responsibility, and contain no stale references.
+- Workflow added or modified (`.github/workflows/*.yml`) → `#` comment block at top must accurately reflect purpose, triggers, and required secrets.
+- CI script added or modified (`ci/*.sh`, `ci/*.py`, `ci/*.qs`) → header comment must accurately describe usage, arguments, and exit codes.
+
+> Full standards: [`.github/prompts/update-docs.prompt.md`](../prompts/update-docs.prompt.md)

.github/prompts/update-docs.prompt.md

@@ -0,0 +1,251 @@
+---
+mode: agent
+description: Update and maintain the OpenStudio Application developer documentation in developer/doc/
+tools:
+  - read_file
+  - grep_search
+  - file_search
+  - semantic_search
+  - replace_string_in_file
+  - create_file
+  - multi_replace_string_in_file
+applyTo: |
+  developer/doc/**/*.md
+  src/**/*.hpp
+  src/**/*.cpp
+  .github/workflows/**/*.yml
+  ci/**
+  CMakeLists.txt
+  src/**/CMakeLists.txt
+---
+
+# Documentation Maintenance Agent
+
+You are a senior developer on the OpenStudio Application project. Your task is to keep the documentation in `developer/doc/` accurate and complete. All documentation is written in Markdown with embedded Mermaid diagrams. The audience is the internal development team (C++/Qt background assumed).
+
+---
+
+## 1. Documentation Structure Map
+
+Every source file has a corresponding documentation home. Consult this map before editing any doc:
+
+```
+developer/doc/
+├── architecture.md              ← CMakeLists.txt, README.md, all module CMakeLists.txt
+├── libraries/
+│   ├── openstudio_app.md        ← src/openstudio_app/CMakeLists.txt + headers
+│   ├── openstudio_lib.md        ← src/openstudio_lib/CMakeLists.txt + headers
+│   ├── shared_gui_components.md ← src/shared_gui_components/CMakeLists.txt + headers
+│   ├── openstudio_qt_utils.md   ← src/openstudio_qt_utils/CMakeLists.txt + headers
+│   ├── model_editor.md          ← src/model_editor/CMakeLists.txt + headers
+│   ├── bimserver.md             ← src/bimserver/CMakeLists.txt + headers
+│   └── utilities.md             ← src/utilities/CMakeLists.txt
+```
+
+---
+
+## 2. Trigger Conditions
+
+Update documentation when ANY of the following changes occur:
+
+| Change | Docs to update |
+|---|---|
+| `CMakeLists.txt` in a module changes (new deps, new targets) | Corresponding library `.md` + `architecture.md` dependency graph |
+| `src/openstudio_qt_utils/` file modified | `libraries/openstudio_qt_utils.md` |
+| Top-level `CMakeLists.txt` changes (version, new sub-project) | `architecture.md` |
+| `conanfile.py` dependency version changes | `architecture.md` tech stack section |
+
+---
+
+## 3. Document Templates
+
+### 3a. Architecture Document (`architecture.md`)
+
+```markdown
+# OpenStudio Application — Architecture
+
+> Version: {version} | Tech stack: C++20, Qt {qt_version}, CMake+Conan 2
+
+## 1. System Context
+
+\`\`\`mermaid
+C4Context
+  title System Context — OpenStudio Application
+  Person(user, "Energy Modeler", "...")
+  System(app, "OpenStudio Application", "...")
+  ...
+\`\`\`
+
+## 2. Container View
+
+\`\`\`mermaid
+C4Container
+  ...
+\`\`\`
+
+## 3. Module Dependency Graph
+
+\`\`\`mermaid
+flowchart LR
+  ...
+\`\`\`
+
+## 4. Technology Stack
+
+| Category | Technology | Version |
+|---|---|---|
+| ...
+
+## 5. Key Design Patterns
+
+...
+
+## 6. CI/CD Integration
+
+...
+
+## 7. Module Index
+
+| Module | Library | Doc |
+|---|---|---|
+| ...
+```
+
+### 3b. Library Document (`libraries/{name}.md`)
+
+```markdown
+# Library: `{name}`
+
+> CMake target: `openstudio_{name}` | Location: `src/{name}/`
+
+## Purpose
+One-paragraph description of responsibility.
+
+## Mermaid Context
+\`\`\`mermaid
+flowchart LR
+  {name}["**{name}**\n..."] --> dep1["dependency"]
+\`\`\`
+
+## Key Classes
+| Class | Role |
+|---|---|
+
+## Dependencies
+| Dependency | Usage |
+|---|---|
+
+## Design Notes
+...
+
+## Key Classes
+
+Class-level documentation is in the corresponding header files under [`src/{name}/`](../../../src/{name}/).
+```
+
+---
+
+## 4. Mermaid Conventions
+
+| Diagram type | When to use | Size limit |
+|---|---|---|
+| `flowchart TD/LR` | System-level context and container views (architecture.md) | — |
+| `flowchart TD` / `LR` | Job step sequences (CI docs), initialization flows | — |
+| `classDiagram` | Class inheritance and key methods | ≤12 nodes |
+| `sequenceDiagram` | Inter-object messaging (class docs) | ≤8 participants |
+
+**Rules:**
+- Never use actor/entity names that contain special characters without quoting them.
+- Avoid placing raw C++ template syntax inside diagram nodes; use simplified names.
+- Always give diagrams a `title` line when C4 context/container type is used.
+- Prefer short, readable labels. Put full detail in prose below the diagram.
+
+---
+
+## 5. Cross-Linking Rules
+
+- `architecture.md` module index must link to every library doc.
+- Use **relative Markdown links** only (e.g., `../libraries/openstudio_lib.md`, not absolute paths).
+
+---
+
+## 6. Step-by-Step Maintenance Procedure
+
+Follow these steps whenever source code or CI configuration changes:
+
+1. **Identify changed files.** Read the diff or PR description to find which `.hpp`, `.cpp`, `.yml`, `CMakeLists.txt`, or `ci/` files were modified.
+
+2. **Map to documentation.** Use the Structure Map (§1) and Trigger Conditions (§2) to determine which `.md` files need updating.
+
+3. **Read the changed source.** Use `read_file` to read the relevant headers and CMake files.
+
+4. **Read the existing doc.** Use `read_file` on the current `.md` to understand what is already correct and what has drifted.
+
+5. **Update the doc.** Use `replace_string_in_file` for targeted edits (prefer this over full rewrites). Update:
+   - Dependency tables and module graphs if CMake targets changed
+   - Tech stack table in `architecture.md` if versions changed
+
+6. **Check for version or dependency changes.** If `CMakeLists.txt` or `conanfile.py` changed dependency versions, update the tech stack table in `architecture.md`.
+
+7. **Verify Mermaid syntax.** Ensure all diagram blocks are syntactically valid Mermaid.
+
+---
+
+## 7. Class Documentation
+
+Class-level documentation lives in `/** */` doc comments in the header files (`src/**/*.hpp`), not in separate Markdown files. When adding a new significant class (base/abstract classes, major controllers, integration points, widely reused components), add a `/** ... */` doc comment block directly above the class declaration describing its purpose.
+
+---
+
+## 8. Comment Correctness and Completeness Checks
+
+When source files are changed, verify that inline comments remain accurate.
+
+### C++ Header Class Comments (`src/**/*.hpp`)
+
+For every significant class (base/abstract, major controller, integration point, widely reused component) that was added or modified:
+
+1. **Presence** — a `/** */` doc comment must appear directly above the class declaration (not a forward declaration).
+2. **Accuracy** — the comment must reflect the class's current responsibility. Check for:
+   - Purpose description that no longer matches the class's role after a refactor
+   - References to removed methods, renamed signals, or deleted dependencies
+3. **Completeness** — if the class is one of the following types, the comment should describe what it owns, what signals it emits, and how it fits into the broader system:
+   - Abstract base / interface classes
+   - Tab-level controllers (`*Controller` owning a `*View`)
+   - Classes bridging external systems (web engine, BIMserver, CLI, network)
+4. **What to skip** — do not add or require doc comments on:
+   - Forward declarations
+   - Member variables, private methods, or trivial getters/setters (unless they have non-obvious side effects)
+   - Private implementation detail classes nested inside a `.cpp`
+   - Thin wrappers or trivial value types with self-explanatory names
+
+### GitHub Actions Workflow Comments (`.github/workflows/*.yml`)
+
+For every workflow file that was added or modified, verify the file-level comment block at the top:
+
+1. **Presence** — a `#`-prefixed comment block must appear before the `name:` line.
+2. **Accuracy** — check that the comment correctly describes:
+   - The workflow's purpose (what it builds, tests, or enforces)
+   - Trigger conditions (branches, tags, events, manual dispatch)
+   - Any required secrets (add or remove as the `secrets:` block changes)
+   - When to run it manually (for `workflow_dispatch` workflows)
+3. **Completeness** — the comment should be enough for a developer to understand the workflow without reading the full YAML. It does not need to enumerate every step.
+
+### CI Helper Scripts (`ci/*.sh`, `ci/*.py`, `ci/*.qs`)
+
+For every script that was added or modified:
+
+1. **Presence** — a comment header describing the script's purpose must be present near the top of the file.
+2. **Accuracy** — check that usage examples, argument descriptions, and exit-code documentation still match the script's actual behaviour.
+
+---
+
+## 9. Scope Exclusions
+
+Never document the following in `developer/doc/` (they are internal plumbing or generated code):
+
+- Contents of `debug/` or `release/` build directories
+- Files under `signatures/`
+- References to BIMserver as this functionality is to be deprecated
+- Generated files under `src/utilities/` (these are `configure_file` outputs)
+- Contents of `ruby/` Ruby gems or vendored external libraries

.github/workflows/app_build.yml

@@ -1,3 +1,21 @@
+# Main build pipeline. Builds the OpenStudio Application on 5 platforms (ubuntu-22.04,
+# ubuntu-24.04, windows-2022, macos-15-intel, macos-15 arm64), runs CTest and benchmarks,
+# applies code signing on tag pushes, and uploads installers to GitHub Releases.
+#
+# Two jobs:
+#   build         - matrix over all 5 platforms
+#   test_package_macos - downloads and verifies the signed macOS DMG (macos-15-intel + arm64)
+#
+# Caching: three independent caches keyed by OS + Conan profile + CACHE_KEY secret:
+#   1. ccache (compiler output cache)
+#   2. Conan package cache
+#   3. Qt + OpenStudio SDK download cache
+# Rotate the CACHE_KEY secret to bust all caches immediately.
+#
+# Required secrets: MACOS_DEVELOPER_ID_APPLICATION_CERTIFICATE_P12_BASE64,
+#   MACOS_DEVELOPER_ID_INSTALLER_CERTIFICATE_P12_PASSWORD, MACOS_KEYCHAIN_PASSWORD,
+#   NOTARIZATION_API_KEY, NOTARIZATION_API_TEAM_ID, NOTARIZATION_API_ISSUER_ID,
+#   SIGNPATH_CI_TOKEN, ANALYTICS_API_SECRET, ANALYTICS_MEASUREMENT_ID, CACHE_KEY
 name: C++ CI for OpenStudioApplication
 
 on:

.github/workflows/check_osm_versions.yml

@@ -1,3 +1,9 @@
+# Ensures all .osm template files bundled in src/openstudio_app/Resources/ have been
+# version-translated to the current OpenStudio SDK version before a PR merges to master.
+# Runs developer/ruby/CheckOSMVersions.rb which verifies each file's OS:Version object.
+#
+# On failure: run the export_standards_data workflow to regenerate the OSM files, or run
+# developer/ruby/UpdateOSMVersions.rb locally and commit the result.
 name: Check OSM Versions
 
 on:

.github/workflows/cla.yml

@@ -1,3 +1,9 @@
+# Enforces the Contributor License Agreement for all external contributors.
+# Uses pull_request_target (runs in base branch context) so it has write access
+# even from fork PRs. Signatures are stored in signatures/version1/cla.json on the
+# develop branch. Contributors sign by commenting the magic phrase on their PR.
+# Organization members and bots are automatically excluded.
+# Required secret: CLA_SECRET (GitHub PAT with repo scope)
 name: "CLA Assistant"
 on:
   issue_comment:
@@ -33,4 +39,4 @@ jobs:
           #custom-pr-sign-comment: 'The signature to be committed in order to sign the CLA'
           #custom-allsigned-prcomment: 'pull request comment when all contributors has signed, defaults to **CLA Assistant Lite bot** All Contributors have signed the CLA.'
           #lock-pullrequest-aftermerge: false - if you don't want this bot to automatically lock the pull request after merging (default - true)
-          #use-dco-flag: true - If you are using DCO instead of CLA
+          #use-dco-flag: true - If you are using DCO instead of CLA

.github/workflows/clangformat.yml

@@ -1,3 +1,8 @@
+# Enforces .clang-format style on all C/C++ files changed in a PR.
+# Runs ci/clang-format.sh which diffs HEAD against the base branch, formats only
+# changed files, and exits 1 if any changes were needed.
+# On failure: download the clang_format.patch artifact and apply with 'git apply clang_format.patch'.
+# Install ci/pre-commit.sh as a git pre-commit hook to catch violations locally.
 name: Clang Format
 
 on:

.github/workflows/cppcheck.yml

@@ -1,3 +1,8 @@
+# Runs cppcheck static analysis on the entire src/ tree.
+# Builds cppcheck 2.9 from source (the Ubuntu package is too old) to ensure
+# consistent results. Uses --enable=all --library=qt --std=c++20 --inconclusive
+# and suppresses useStlAlgorithm.
+# Output is colorized by ci/colorize_cppcheck_results.py and uploaded as an artifact.
 name: cppcheck
 
 on:
@@ -43,7 +48,6 @@ jobs:
             --library=qt \
             --template='[{file}:{line}]:({severity}),[{id}],{message}' \
             --force -q -j $(nproc) \
-            -i ./src/qtwinmigrate \
             ./src 2>&1 | tee cppcheck.txt
 
     - name: Parse and colorize cppcheck