Clarify the shim resolution order in the docs.  Code still needs to catch up.