docs: add feature and troubleshooting documentation (#463)

Add a framework for feature documentation, and start populating it with
our SDK documentation.

This framework is as follows:
- internal/docs/**.src.md is the markdown source for the docs/
  directory.
- The x/example/internal/cmd/weave tool is used to compile these docs to
  the top-level docs, supporting both linked code samples and generated
  tables of contents.
- The readme-check workflow is updated to check these docs as well.
- The structure of these docs follows the MCP spec.
- Wherever possible, example code is linked from actual Go documentation
  examples, so that it is testable.

Some minor modifications to the weave tool were made to support this
framework.

Additionally, partially fill out this documentation with content on
base protocol and client features, as well as troubleshooting help.

Along the way, a bug was encountered that our LoggingTransport was not
concurrency safe. This is fixed with a mutex.

Fixes https://github.com/modelcontextprotocol/go-sdk/issues/466
Fixes https://github.com/modelcontextprotocol/go-sdk/issues/409
Updates https://github.com/modelcontextprotocol/go-sdk/issues/442

.github/workflows/readme-check.yml

@@ -1,11 +1,13 @@
 name: README Check
 on:
-  workflow_dispatch:  
+  workflow_dispatch:
   pull_request:
     paths:
       - 'internal/readme/**'
       - 'README.md'
-  
+      - 'internal/docs/**'
+      - 'docs/**'
+
 permissions:
   contents: read
 
@@ -17,15 +19,15 @@ jobs:
       uses: actions/setup-go@v5
     - name: Check out code
       uses: actions/checkout@v4
-    - name: Check README is up-to-date
+    - name: Check docs is up-to-date
       run: |
-        go generate ./internal/readme
+        go generate ./...
         if [ -n "$(git status --porcelain)" ]; then
-          echo "ERROR: README.md is not up-to-date!"
+          echo "ERROR: docs are not up-to-date!"
           echo ""
-          echo "The README.md file differs from what would be generated by `go generate ./internal/readme`."
-          echo "Please update internal/readme/README.src.md instead of README.md directly,"
-          echo "then run `go generate ./internal/readme` to regenerate README.md."
+          echo "The docs differ from what would be generated by `go generate ./...`."
+          echo "Please update internal/**/*.src.md instead of directly editing README.md or docs/ files,"
+          echo "then run `go generate ./...` to regenerate docs."
           echo ""
           echo "Changes:"
           git status --porcelain
@@ -34,4 +36,4 @@ jobs:
           git diff
           exit 1
         fi
-        echo "README.md is up-to-date"
+        echo "Docs are up-to-date."