Improve glossary

[tsmbland]

Description

This makes the glossary a bit more comprehensive.

A few other small changes thrown in:

• there was some incorrect info in the circularity model readme, and I also noticed that increasing capacity_margin is no longer necessary
• Added info about the validate command to the user guide
• Add link to the muse2 settings command docs to the user guide
• Refer to MUSE2 throughout rather than MUSE

Fixes # (issue)

Type of change

• Bug fix (non-breaking change to fix an issue)
• New feature (non-breaking change to add functionality)
• Refactoring (non-breaking, non-functional change to improve maintainability)
• Optimization (non-breaking change to speed up the code)
• Breaking change (whatever its nature)
• Documentation (improve or add documentation)

Key checklist

• All tests pass: $ cargo test
• The documentation builds and looks OK: $ cargo doc
• Update release notes for the latest release if this PR adds a new feature or fixes a bug
  present in the previous release

Further checks

• Code is commented, particularly in hard-to-understand areas
• Tests added that prove fix is effective or that feature works

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.35%. Comparing base (131ca67) to head (9a3699d).
⚠️ Report is 35 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1501      +/-   ##
==========================================
+ Coverage   90.31%   90.35%   +0.03%     
==========================================
  Files          60       61       +1     
  Lines        8663     8850     +187     
  Branches     8663     8850     +187     
==========================================
+ Hits         7824     7996     +172     
- Misses        525      529       +4     
- Partials      314      325      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR expands and refines the documentation for MUSE2—primarily by making the glossary substantially more comprehensive—while also updating the circularity example/docs and refreshing the associated golden test data outputs.

Changes:

• Greatly expands docs/glossary.md with clearer, more detailed definitions of key MUSE2 concepts.
• Improves user-facing documentation around model validation and settings management (muse2 validate, muse2 settings ...), and standardises references to “MUSE2”.
• Updates the circularity example (removing capacity_margin) and updates expected outputs in tests/data/* accordingly.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/data/circularity/commodity_prices.csv	Updates golden commodity price outputs for circularity scenario.
tests/data/circularity/commodity_flows.csv	Updates golden commodity flow outputs for circularity scenario.
tests/data/circularity/asset_capacities.csv	Updates golden asset capacity outputs for circularity scenario.
tests/data/circularity_npv/commodity_prices.csv	Updates golden commodity price outputs for circularity NPV scenario.
tests/data/circularity_npv/commodity_flows.csv	Updates golden commodity flow outputs for circularity NPV scenario.
tests/data/circularity_npv/asset_capacities.csv	Updates golden asset capacity outputs for circularity NPV scenario.
schemas/settings.yaml	Corrects settings file location guidance (platform config dir) and points to muse2 settings path.
examples/circularity/README.txt	Removes outdated notes about pricing strategy and needing a wider capacity_margin.
examples/circularity/model.toml	Removes capacity_margin from the example model configuration.
docs/user_guide.md	Adds muse2 validate guidance, links to settings docs, and standardises “MUSE2” wording.
docs/glossary.md	Major glossary expansion and refinement of definitions and terminology.

Suppressed comments (1)

docs/glossary.md:196

• Markdown emphasis for plurals is currently split ("Processes"), which renders awkwardly. Use a fully pluralised emphasised term ("Processes") instead.

Commodities*. *Process*es have economic attributes of *Capital Cost*, *Fixed Operating Cost* per

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dalonsoa]

This looks fantastic - and a lot of work! Not sure if it would help or not, but as this is a list of things, I sort of feel they will be easier to read if we use bullet points.

[dc2917]

Must be between 0 and 1

inclusive, presumably?

[tsmbland]

Yes