[j-emberton]

Summary

Rework the README to show what Bilt does before getting into installation and reference material. It now starts with solving one equation in different directions, then covers reusable systems, coupled linear solves, physical quantities and uncertainty propagation with named tensors.

The illustrations use a consistent engineering-diagram style. They are intended to show the relationships, leaving the explanation to the surrounding text.

Changes

• Reorganise the README around concrete modelling examples, with links to the full documentation.
• Add four figures covering forward and inverse calculations, two springs with a coupled solve, unit conversion and dimensional checks, and uncertainty propagation.
• Generate the figures from scripts/readme_figures.json using the dependency-free scripts/generate_readme_svgs.py. The SVG outputs are committed so GitHub can render them.
• Add python scripts/generate_readme_svgs.py --check to CI to catch outdated figures.

Checks

GitHub CI passes, including the generated-figure check, Ruff, type checking, tests, documentation build and prek.

The README code snippets have not been separately tested in a fresh installation.

[Copilot]

🟢 Approval recommended

No active review issues are reported for the README and accompanying SVG updates.

No open issues 🎉

What changed in this PR

Reworks Bilt’s README into a visual introduction to its equation-oriented modelling capabilities, supported by concise examples and links to detailed guides.

Changes:

• Adds four SVG illustrations covering model reuse, coupled systems, dimensional analysis, and uncertainty propagation.
• Introduces energy-conversion and sampled-uncertainty examples, with explicit limits on statistical calibration.
• Updates source-installation instructions to Python 3.15+ and summarizes current capabilities and limitations.

File	Description
README.md	Reorganizes the introduction around visual examples, guides, installation, and scope.
.github/​assets/​bilt-uncertainty-propagation.svg	Illustrates output-energy samples mapped to inferred efficiency samples.
.github/​assets/​bilt-systems-of-systems.svg	Shows reusable spring components and a coupled linear solve.
.github/​assets/​bilt-multiple-questions.svg	Shows one equation answering forward, inverse, and parameter-identification questions.
.github/​assets/​bilt-dimensional-analysis.svg	Illustrates compatible-unit conversion and dimensional validation.

_{Review effort: Balanced}

[brocksam]

I think the restructure is good. Getting across the key selling points first is good and I think you've balanced getting enough detail in without letting it run too long well. I probably wouldn't want the overall length to grow too much longer. Code snippets for systems-of-systems and quantities/tensors would also be ideal, but appreciate that'd bring extra length.

My big worry is that it does scream AI at a glance, and I think there's a serious risk that that turns of potential users immediately. I think this is one place where someone putting effort in to writing this as a human would be worth it. But important to get the content solidified before either of us does that.

[brocksam]

These diagrams are inconsistent from one another, which I think unfortunately risks the repo screaming "AI slop" to anyone glancing at it. It'd be worth putting some work in with Claude Design to make these look more polished and consistent. Things like:

• Thinking more deeply about the content in each one.
• Simpler colour scheme.
• Consistent use of LaTeX for math for proper rendering.
• Consistent design system for font use.

[j-emberton]

Might ask Noli to take a quick look as well

[j-emberton]

I think the restructure is good. Getting across the key selling points first is good and I think you've balanced getting enough detail in without letting it run too long well. I probably wouldn't want the overall length to grow too much longer. Code snippets for systems-of-systems and quantities/tensors would also be ideal, but appreciate that'd bring extra length.

My big worry is that it does scream AI at a glance, and I think there's a serious risk that that turns of potential users immediately. I think this is one place where someone putting effort in to writing this as a human would be worth it. But important to get the content solidified before either of us does that.

The images are fully procedurally generated now, but I did use AI to generate the concept.

happy to move to a different aesthetic if needed.

I like the diff-soup approach, but we do need a different concept here.
https://github.com/stmorgenstern/diff-soup

[brocksam]

New versions definitely look more consistent and cleaner, although they're definitely screaming Claude Design now!

[brocksam]

Could this go in the pre-commit hooks? Does it run fast enough?

[j-emberton]

I'll experiment