After much struggle trying to get Entities#intersect_with, reading all of the examples but failing in bizarre ways, I think I finally wrestled this beast to the ground. Since I didn't see this explanation in any search hits, I thought I'd share it here.
If you ponder Entities#intersect_with, you will notice a peculiar aspect: there are three Entities collections involved in the operation, but only two Transformations. The only possible interpretations are that the same Transformation is secretly applied to two of the Entities, or that one of the Entities collections is used untransformed. It turns out that the final Entities collection passed must already be in model coordinates; it will not be transformed before calculating the intersection. I was trying to use a ComponentDefinition's Entities for that third argument, and treating it as if it is already in model coordinates causes very strange results!
All of the examples I found used Groups, and despite having an associated Transformation, the Entities in a Group are actually captured in model coordinates at all times. That is, when you transform a Group the Transformation is remembered but the locations of all Vertices in the Group are recalculated immediately in model coordinates.
[edit: the above statement is false. The vertices in a Group are not recalculated when, for example, you move the Group. Instead, the movement is captured in the Group's Transformation. But a Group is acceptable as the final argument, ents3, because it carries this transformation along with it. This allows intersect_with to transform the Group's Entities to model coordinates. Faces and Edges do not carry their own transformations, though.]
So, here's a reinterpretation of the API doc:
ents_arr = ents1.intersect_with(recurse, trans1, ents2, trans2, hidden, ents3)
The Entities in ents1 are transformed to model coordinates using trans1. This allows ents1 to come from a ComponentDefinition and trans1 to correspond to a ComponentInstance at a particular location and orientation (that actual instance does not need to exist in the model!)
The intersection is calculated between (transformed) ents1 and (untransformed) ents3.
The results are returned as ents_arr and are also placed into ents2 after transformation by trans2.
Note that if trans2 is not the actual transformation of ents2, the results may go to strange locations.
Steve