if I use do on a file, I get a context for wantarray to work on even if it's at the top level of the file.
I'm not sure what you mean by this ...
If you use the do operator to evaluate the contents of a file then code in that file gets the context of the do, so in those circumstances wantarray is meaningful to code at the top level of a file.
... but here's an example in which wantarray doesn't seem to work at the top level
Well done. Now the actual purpose of this thread is to find a form of words that distinguishes these cases, so the docs can be patched to avoid the current inaccuracy which suggests that wantarray is never meaningful at the top level.
Smylers