Move docs/ package mirror into document-navigator plugin

Relocate the ~6k-file docs tree from the repo root into
plugins/document-navigator/docs/ so the plugin is self-contained and
portable. docs/superpowers/ (specs and plans) stays at the repo root.

Moved via cp+rm rather than git mv because directory rename() fails with
EPERM on this WSL /mnt DrvFs mount; git rename-detection pairs the
identical-content files at commit time.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

plugins/document-navigator/docs/api-stack/api/api-graphql-apollo/src/subscriptions/subscriptions.md

@@ -0,0 +1,81 @@
+# `subscriptions` — `graphql-ws` bridge
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`subscriptions` runs a GraphQL subscription document against a wired
+schema, returning the `AsyncIterable<ExecutionResult>` the engine
+forwards over the host's `api-ws` transport. Subscriptions ride
+`graphql-ws` semantically; this module is the framework-agnostic core
+that the engine's transport adapter wraps.
+
+When the host has not wired an `api-ws` engine, the
+`assertSubscriptionTransport` guard raises
+`GRAPHQL_APOLLO.SUBSCRIPTION_TRANSPORT_UNAVAILABLE` so that the missing
+infrastructure surfaces at the first subscription frame — not later
+when a publish silently never reaches a subscriber.
+
+## Features
+
+- Direct `graphql.subscribe()` delegation — no extra framing.
+- Accepts both `DocumentNode` and SDL string for the operation.
+- Wraps a single-result rejection in a one-shot AsyncIterable so the
+  caller's frame loop sees one error frame and closes cleanly.
+- Transport guard raises a typed `GraphqlApolloError` with the
+  `SUBSCRIPTION_TRANSPORT_UNAVAILABLE` code.
+- Validates the document contains a subscription operation — non-
+  subscription operations raise
+  `GRAPHQL_APOLLO.VALIDATION_FAILED`.
+
+## Usage: Basic
+
+```ts
+import { runSubscription } from "@suaveplan/api-graphql-apollo/subscriptions";
+
+const iter = await runSubscription({
+    schema,
+    document: "subscription { ticks }",
+    contextValue: { tenantId: "t_1" },
+});
+for await (const frame of iter) {
+    console.log(frame);
+}
+```
+
+## Usage: Advanced
+
+Pair the runtime guard with the host's `api-ws` wiring so subscription
+frames are rejected at the wire boundary when the transport is not
+configured:
+
+```ts
+import {
+    assertSubscriptionTransport,
+    runSubscription,
+} from "@suaveplan/api-graphql-apollo/subscriptions";
+
+const transport = host.adapters.ws ?? null;
+assertSubscriptionTransport(transport);
+const iter = await runSubscription({ schema, document, contextValue });
+```
+
+## API Reference
+
+- `SubscriptionTransport` — `{ protocol: "graphql-ws" }`.
+- `assertSubscriptionTransport(transport | null)` — throws
+  `GraphqlApolloError` on miss.
+- `runSubscription({ schema, document, variableValues?,
+  operationName?, contextValue })`.
+
+## Implementation Notes
+
+When `graphql.subscribe()` returns a single `ExecutionResult` (e.g.
+the subscribe field threw synchronously), the helper wraps it in a
+single-iteration AsyncIterable so callers' frame loops handle the
+error path identically to the streaming path. The validation step
+sniffs the document for any `OPERATION_DEFINITION` of kind
+`subscription`; documents that contain only query/mutation operations
+reject with `VALIDATION_FAILED`.