Document new polymorphism stuff

[benjie]

I had to explain this to ChatGPT for help coming up with names, this might be a good source of documentation:

https://chatgpt.com/share/6815fd4a-9b54-8012-b193-de3832f88dc2

[benjie]

I've written docs for this but I'm not sure it's clear - really need someone to work through it and help me get the wording crisp.