caddiff 0.3.4__tar.gz

caddiff-0.3.4/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The caddiff Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

caddiff-0.3.4/NOTICE

@@ -0,0 +1,18 @@
+caddiff
+git diff for CAD assemblies
+
+Copyright 2026 The caddiff Authors
+
+This product includes software developed by third parties. The third-party
+components, their licenses, and the form in which each one is distributed are
+listed in THIRD_PARTY_LICENSES.md.
+
+The source code of this project is licensed under the Apache License, Version
+2.0 (see LICENSE). The third-party components that are bundled inside the
+published Docker image are not covered by that license: each of them remains
+under its own upstream license. Read THIRD_PARTY_LICENSES.md before
+redistributing the image or an image derived from it.
+
+This product includes Open CASCADE Technology (OCCT), distributed under the
+GNU Lesser General Public License version 2.1 with the Open CASCADE Exception
+1.0.

caddiff-0.3.4/PKG-INFO

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: caddiff
+Version: 0.3.4
+Summary: git diff for CAD assemblies — compare two STEP/STP assemblies and show what changed
+Author: The caddiff Authors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/angel291592/caddiff
+Project-URL: Documentation, https://github.com/angel291592/caddiff/tree/main/docs
+Project-URL: Demo, https://angel291592.github.io/caddiff/report.html
+Project-URL: Changelog, https://github.com/angel291592/caddiff/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/angel291592/caddiff/issues
+Keywords: cad,step,stp,diff,freecad,bom,assembly,git,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: pptx
+Requires-Dist: python-pptx>=0.6.23; extra == "pptx"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+<div align="center">
+
+# caddiff
+
+English | [简体中文](https://github.com/angel291592/caddiff/blob/main/README.zh-CN.md)
+
+**git diff for CAD assemblies.**
+
+Two STEP files in, one picture of *what changed* out — plus a change list your CI can gate on.
+
+[![CI](https://github.com/angel291592/caddiff/actions/workflows/ci.yml/badge.svg)](https://github.com/angel291592/caddiff/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/angel291592/caddiff/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+
+</div>
+
+![caddiff highlighting a moved part and a removed feature](https://raw.githubusercontent.com/angel291592/caddiff/main/docs/images/hero.png)
+
+> Green-ish magenta marks the changed geometry; the red box locates it; the blue arrow
+> shows a 5.00 mm displacement. Both images are generated by `caddiff` from the synthetic
+> fixture in [`examples/`](https://github.com/angel291592/caddiff/tree/main/examples) — no customer data anywhere in this repo.
+> **[Browse the full sample report, rendered online, no install needed →](https://angel291592.github.io/caddiff/report.html)**
+
+---
+
+## The problem
+
+You put your CAD in git. Now someone asks: *"what actually changed between v1.2 and v1.3?"*
+
+`git diff` is useless here. A STEP file is plain text, so git prints four thousand lines of
+coordinates and tells you nothing. Worse, git will happily **merge** two STEP files into a
+file that is syntactically valid and geometrically wrong — and nothing warns you.
+
+Commercial CAD suites sell a fix for this (SOLIDWORKS Compare, TransMagic, 3DViewStation).
+The open-source side had almost nothing: the few projects in this space render a visual
+diff and stop there — no BOM alignment, no report, no CI story.
+
+`caddiff` is the missing piece: a command-line tool that answers *what changed* with a
+picture and a machine-readable list.
+
+---
+
+## Quick start
+
+### Docker (recommended — nothing to install)
+
+```console
+$ docker run --rm -v "$PWD:/data" ghcr.io/angel291592/caddiff:v0.3.4 \
+    diff /data/old.stp /data/new.stp -o /data/report
+```
+
+`v0.3.4` is the released image. An `edge` tag also tracks `main` if you want to live on
+top of the tree — but for anything you gate a CI run on, pin a released tag (or a digest).
+
+### Local install
+
+`caddiff` itself has **zero third-party dependencies** — but the geometry and rendering
+steps run inside FreeCAD, so `FREECAD_PYTHON` must point at an interpreter that can
+`import FreeCAD`:
+
+```console
+$ pip install caddiff          # add [pptx] if you want --pptx
+$ export FREECAD_PYTHON=/path/to/FreeCAD/bin/python.exe   # Windows: the FreeCAD distribution ships its own python
+$ export FREECAD_PYTHON=/usr/bin/python3                  # Linux: the system python3,
+$ export PYTHONPATH=/usr/lib/freecad/lib                  #         with FreeCAD's modules on the path
+$ caddiff diff old.stp new.stp -o report
+```
+
+On Linux, do **not** point `FREECAD_PYTHON` at `.../freecad/bin/freecad-python3`: that file
+is the FreeCAD **GUI application**, so handing it a script opens the GUI and never returns.
+The system `python3` + `PYTHONPATH` above is what works, and it is how the Docker image is
+configured (see [`docs/pipeline.md`](https://github.com/angel291592/caddiff/blob/main/docs/pipeline.md)).
+
+If `FREECAD_PYTHON` is unset, `caddiff` searches the usual Linux locations and `PATH`, and
+**fails with an actionable message** rather than silently falling back to a Python that
+cannot import FreeCAD.
+
+### With `git difftool`
+
+So that `git diff for CAD assemblies` is literally true:
+
+```console
+$ git config --global difftool.caddiff.cmd 'caddiff difftool "$LOCAL" "$REMOTE"'
+$ git difftool -t caddiff HEAD~1 -- bracket.stp
+```
+
+See [`docs/git-integration.md`](https://github.com/angel291592/caddiff/blob/main/docs/git-integration.md) for why CAD files need
+`.gitattributes` treatment and how to pick revisions.
+
+### As a GitHub Action (pull-request gate)
+
+The repo ships a ready-made Action that pulls the same prebuilt image, runs the diff on
+two files in your repo, and uploads the report directory as a workflow artifact:
+
+```yaml
+- uses: angel291592/caddiff@v0.3.4
+  id: caddiff
+  with:
+    old: models/base.stp
+    new: models/pr.stp
+    image: ghcr.io/angel291592/caddiff:v0.3.4
+
+- name: React to differences
+  if: steps.caddiff.outputs.has-differences == 'true'
+  run: echo "::warning::${{ steps.caddiff.outputs.diff-count }} CAD change(s) detected"
+```
+
+Outputs read from `diff_manifest.json` (`has-differences`, `diff-count`, `report-dir`) — the
+action fails only on exit code 2 (caddiff could not run); exit code 1 (differences
+found) is a result, and the report is still uploaded.
+
+`image:` is spelled out on purpose. `@v0.3.4` resolves `action.yml` from the `v0.3.4`
+tag, and that tag's default is frozen at the *previous* release — so without this line
+the action and the geometry engine would run different versions. Same rule as the
+`docker run` above: pin the image, not the branch.
+
+Known limits: fork PRs cannot comment on the PR with the default read-only token, and
+the report is delivered as an artifact rather than a PR comment — see the notes at the
+top of [`action.yml`](https://github.com/angel291592/caddiff/blob/main/action.yml).
+
+---
+
+## What it detects
+
+| Change type | Example | How it is reported |
+|---|---|---|
+| **Part added / removed** | a bracket dropped from the assembly | BOM-level: listed in `summary.bom_added` / `bom_removed` |
+| **Instance count changed** | 2 screws became 4 | BOM-level: listed in `summary.bom_count_mismatch` |
+| **`moved`** | same part, translated or rotated | displacement in mm/°, blue arrow on the image |
+| **`shape_changed`** | material added or removed | boolean symmetric difference, magenta highlight, volume delta |
+
+Parts that could **not** be compared (too many faces, boolean timeout, no solid shape) are
+never silently dropped — they appear in `summary.skipped_parts` with a reason. "Not
+mentioned" must never be readable as "no difference".
+
+---
+
+## What you get
+
+```
+report/
+├── diff_manifest.json     machine-readable contract (start here in CI)
+├── report.html            human-readable report with the images inline
+├── report.md              same content as Markdown (good for PR comments)
+├── images/*.png           overview + old/new close-ups per change
+├── compare.pptx           only with --pptx
+├── bom_diff.json          intermediate
+└── geom_diff.json         intermediate
+```
+
+Each change gets an **automatically chosen viewpoint**: `caddiff` scans 26 candidate
+directions (6 faces + 12 edges + 8 corners), scores each on how much of the highlighted
+geometry is visible and how readable the framing is, and picks the winner. When the change
+is buried inside the assembly it says so on the image instead of pretending the shot is fine.
+
+---
+
+## Exit codes — use it as a CI gate
+
+| Code | Meaning |
+|---|---|
+| `0` | no differences |
+| `1` | differences found |
+| `2` | the run failed (bad input, timeout, crash) |
+
+```yaml
+- name: Check geometry changes
+  run: |
+    docker run --rm -v "$PWD:/data" ghcr.io/angel291592/caddiff:v0.3.4 \
+      diff /data/base.stp /data/pr.stp -o /data/report
+```
+
+The distinction between `1` and `2` matters: a crashed FreeCAD must never look like
+"nothing changed".
+
+---
+
+## How it compares
+
+There are two different things people mean by "CAD diff", and they are not competitors —
+they are the two halves of one loop. Here is where `caddiff` sits.
+
+| | **caddiff** | text-to-CAD tools<br><sub>[text-to-cad](https://github.com/earthtojake/text-to-cad), [CADAM](https://github.com/Adam-CAD/CADAM)</sub> | SOLIDWORKS Compare<br><sub>commercial revision checkers</sub> |
+|---|---|---|---|
+| **What it is for** | verify what changed between two revisions | generate / edit a model from a prompt | verify revisions |
+| Answers "did this model change, and how?" | ✅ deterministic geometry comparison | ❌ has no such notion | ✅ |
+| Works on a file pair you already have | ✅ | ❌ needs a prompt and a regeneration | ✅ |
+| Machine-readable change list | ✅ `diff_manifest.json` | ❌ | ❌ |
+| Gates a pull request | ✅ exit codes `0/1/2` | ❌ | ❌ |
+| Headless / runs in a container | ✅ | varies | ❌ |
+| Needs a CAD licence | ❌ | ❌ | ✅ |
+| Open source | ✅ Apache-2.0 | ✅ (varies) | ❌ |
+
+**The complement, not the rival.** text-to-CAD tools are extremely good at *making*
+changes and have nothing to say about *verifying* them. That gap widens as more edits are
+produced by agents instead of hands:
+
+```console
+# an agent (or you) just rewrote the bracket
+$ caddiff diff old.stp new.stp -o report
+$ echo $?
+1        # something changed — here is exactly what, and by how much
+```
+
+If you generate models with a text-to-CAD tool, `caddiff` is what you run **after** it.
+
+**Versus the commercial revision checkers.** They solve the same problem well, and they
+cost a licence per seat, need the CAD application installed, and cannot run in CI. That is
+the entire reason this project exists — see [The problem](#the-problem).
+
+> On the open-source side, a handful of projects in this space render a visual diff, and
+> none of them ship BOM-level alignment, a machine-readable manifest, or CI exit codes.
+> That is the gap `caddiff` fills.
+
+---
+
+## Benchmarks (measured, not estimated)
+
+All numbers below are wall-clock, software rendering, no GPU. Rendering dominates:
+each change costs one 26-direction scan (≈0.85 s per direction) plus three images.
+
+| Input | Where it ran | Changes found | Wall clock |
+|---|---|---|---|
+| 3-part synthetic assembly ([`examples/`](https://github.com/angel291592/caddiff/tree/main/examples)) | source checkout, Windows + FreeCAD 1.1.3 | 2 | **≈80 s** |
+| 3-part synthetic assembly, same fixture | official image, Linux + FreeCAD 0.21.2 | 2 | **≈35 s** |
+| 55-part production assembly | source checkout, Windows + FreeCAD 1.1.3 | 3 | **290–366 s** |
+
+The image is faster on the small fixture because the container is a clean Linux
+filesystem — no Windows Defender scanning of the intermediate STEP/BREP files. Do not
+read that as 0.21 being faster than 1.1.3; the two rows differ in more than one way.
+
+Reproduce the first row yourself:
+
+```console
+$ python caddiff/make_moved_fixture.py examples/fixtures
+$ caddiff diff examples/fixtures/moved_old.stp examples/fixtures/moved_new.stp -o out
+```
+
+We are not claiming a speed record. If you need sub-second diffs on huge assemblies,
+this is not the tool for you yet — see the roadmap.
+
+---
+
+## What this does **not** do
+
+Being explicit about the boundaries, because a tool that over-promises is worse than no tool:
+
+- **No tolerance analysis or GD&T.** `shape_changed` means "the boolean symmetric
+  difference is non-empty", not "this is out of tolerance".
+- **No free-form surface deviation maps.** We compare solids, not point clouds.
+- **No huge assemblies.** The render step is serial; a 55-part assembly already takes
+  minutes. There is no upper bound enforced, but the experience degrades.
+- **Part pairing is heuristic.** Same-named parts are matched by bounding-box proximity
+  with a 50 % volume guard. This works well for the common "same assembly, edited in
+  place" case and is **known to be weak** when parts are renamed wholesale or the whole
+  assembly is moved. Unmatched parts are reported, never guessed. Measured on 24 pairs of
+  real public assemblies: every structural change was caught, but 7 of 15 structurally
+  unchanged pairs still report BOM add/remove pairs purely from **renames** (human renames,
+  exporter auto-names, even case-only changes) — the name really did change, and geometry
+  cannot pair across names, so read a symmetric added/removed list as "something was
+  renamed". A same-named part that changed beyond the 50 % pairing guard is reported as a
+  whole-part change (degraded, clearly labelled), never dropped.
+- **No merge.** `caddiff` tells you what changed. It does not merge two STEP files, and it
+  will not try.
+- **No hosted service.** Everything runs locally or in your own CI. Nothing is uploaded.
+
+---
+
+## How it works
+
+```
+old.stp ─┐
+         ├─► [1] BOM alignment        (pure Python — part names, instance counts)
+new.stp ─┘        │
+                  ├─► [2] geometric diff     (FreeCAD: classify identical/moved/shape_changed,
+                  │                           boolean symmetric difference in a killable subprocess)
+                  ├─► [3] render             (FreeCAD GUI + 26-direction viewpoint search → PNG)
+                  └─► [4] report             (manifest JSON + HTML + Markdown; PPTX on demand)
+```
+
+Two design rules that are load-bearing:
+
+- **Every expensive geometry operation runs in a subprocess with a hard timeout.** Face
+  count does not predict boolean cost — we measured a 912-face part whose single `cut`
+  ran past 840 s. A face-count gate alone cannot catch that; only a killable subprocess can.
+- **FreeCAD is only ever talked to via subprocess + files.** No compiled extensions, no
+  `dlopen`, no shared memory. This keeps the LGPL/GPL boundary clean (see
+  [`THIRD_PARTY_LICENSES.md`](https://github.com/angel291592/caddiff/blob/main/THIRD_PARTY_LICENSES.md)) and keeps crashes contained.
+
+Technical deep-dive: [`docs/pipeline.md`](https://github.com/angel291592/caddiff/blob/main/docs/pipeline.md).
+
+---
+
+## Roadmap
+
+- **v0.1 – v0.3** (released) — `caddiff diff`: BOM alignment, geometric diff, rendering,
+  HTML/Markdown/JSON reports, Docker image, GitHub Action, CI exit codes.
+- **next** — an MCP server so an agent that just edited a model can verify its own work
+  against the previous revision.
+- **later** — `caddiff check` (FEA sanity checks) and `caddiff build` (sandboxed modeling).
+  The namespace is reserved; nothing is promised.
+
+[![Star History Chart](https://api.star-history.com/image?repos=angel291592/caddiff&type=Date)](https://star-history.com/#angel291592/caddiff&Date)
+
+---
+
+## Contributing
+
+Bug reports, fixture pairs, and pull requests are welcome — see
+[`CONTRIBUTING.md`](https://github.com/angel291592/caddiff/blob/main/CONTRIBUTING.md). Please **never attach a real customer model** to an
+issue: CAD files routinely contain trade secrets, and the derived PNG/JSON/HTML carry the
+part names too. Use a minimal synthetic sample.
+
+Security reports: [`SECURITY.md`](https://github.com/angel291592/caddiff/blob/main/SECURITY.md).
+
+---
+
+## License
+
+Repository source code is **Apache-2.0** ([`LICENSE`](https://github.com/angel291592/caddiff/blob/main/LICENSE)).
+
+The Docker image **bundles third-party components under their own licenses** — FreeCAD
+(LGPL-2.1-or-later, and its distribution also contains GPL-licensed files), OpenCASCADE
+(LGPL-2.1 with the OCCT exception), numpy, Pillow, python-pptx. Those are *not* covered by
+the Apache-2.0 license of this repository. Full details, including how to obtain the
+corresponding source, are in [`THIRD_PARTY_LICENSES.md`](https://github.com/angel291592/caddiff/blob/main/THIRD_PARTY_LICENSES.md).
+
+This project is not affiliated with or endorsed by the FreeCAD project or the FreeCAD
+Project Association. It uses Open CASCADE Technology.