Hi Matt,
This is actually something we were discussing yesterday because we felt it was unclear and you've hit a lot of the points we've discussed in your message. Thank you for getting in contact this will allow use to share this with everyone. So to be clear...
Our documentation & gatsby-source-prismic-graphql
We are going to remove the current documentation for Gatsby, which is currently created around the gatsby-source-prismic-graphql plugin, because like you said this is confusing and this isn't what we recommend. In place of the documentation for the moment we will have an article explaining our position and our recommendations.
The fork that we have created of this plugin is to help anyone currently using it on live websites so that we have control of publishing updates, but you were correct in guessing @marc.mcintosh has been on vacation 
. Although this doesn't solve the deeper issues, as we discussed in the blog post.
Using Prismic Previews with React
For the moment, because Prismic Previews don’t work with Gatsby the way we want, we recommend the more stable Next.js to create Statically Generated React projects.
If you want to create a new Gatsby project
We suggest using Angelo’s gatsby-source-prismic plugin and his documentation for it on Github, because as explained in the blog post..
This plugin is once again community-created, but it doesn’t rely on GraphQL, is future-proofed for Gatsby Cloud, and we are very heavily involved in maintaining it.
The fork of this that we have on our Github was just for creating a PR, everyone should use the kit on Angelo's github.
What is our plan for the future?
We have explained this in more detail in the blog post, but in the immediate future our team will perform a proof on concept with another approach Gatsby recommended this September.
Depending on the outcome of that we will know if we will either create our own in-house Gatsby plugin or invest further in to Angelo's plugin. Once this is clearer for us we will being planning our new Gatsby documentation based around this.
Hopefully this makes things clearer. We share your frustration in what's happening, but like we said before this has been as huge learning process for us and fingers crossed things will be a lot smoother in the future if we are ever in the same position.
Let me know if you have any further questions.
Thanks.