docs: restructure into topical sections and add the four most-asked-for pages (#3044)

examples/README.md

@@ -16,7 +16,7 @@
 - [`clients/`](clients/) and the remaining [`servers/`](servers/) directories
   (`simple-*`, `sse-polling-demo`, `structured-output-lowlevel`) — standalone
   v1-era projects retained pending consolidation into `stories/` (the
-  `simple-auth` pair is still linked from `docs/advanced/`).
+  `simple-auth` pair is still linked from `docs/run/authorization.md` and `docs/client/oauth-clients.md`).
 
 For real-world servers see the
 [servers repository](https://github.com/modelcontextprotocol/servers).

examples/stories/subscriptions/README.md

@@ -56,5 +56,5 @@ uv run python -m stories.subscriptions.client --http --server server_lowlevel
 ## See also
 
 `streaming/` (request-scoped notifications), `events/` (the events extension
-on top of this channel, deferred), and `docs/advanced/subscriptions.md` (the
+on top of this channel, deferred), and `docs/handlers/subscriptions.md` (the
 narrative version).