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/wasm-compiler-javy/src/bin/cli.md

@@ -0,0 +1,57 @@
+# `suaveplan-wasm-compile` — CLI binary
+
+## Purpose
+
+`suaveplan-wasm-compile` is the package's command-line entry. It parses an argv tail into a `CliInvocation`, calls `compilePluginToWasm`, and emits the result as a single-line JSON record on stdout (success) or as a structured error envelope on stderr (failure). The contract is machine-friendly so CI workflows can pipe the success line into downstream tools (`jq`, sandbox install scripts) and surface failures with `code`/`message`/`context` triplets that operators can grep against.
+
+The CLI is intentionally thin — every argument has a one-to-one mapping to a `compilePluginToWasm` option, and there is no second-tier configuration (env vars, config files). This keeps the CLI's behaviour identical to programmatic callers; a `suaveplan-wasm-compile` failure reproduces by calling `compilePluginToWasm` with the same options.
+
+## Features
+
+- `--out-dir <dir>` mandatory.
+- `--optimize-for size|speed` defaulting to `size`.
+- `--sourcemaps` boolean toggle.
+- `-h`/`--help` prints the usage block and exits 0.
+- Structured JSON IO on every code path.
+- `CliDeps` injection for tests so stdout / stderr / exit can be captured without the test runner observing the actual process streams.
+
+## Usage: Basic
+
+```sh
+bunx suaveplan-wasm-compile ./src/plugin/index.ts --out-dir /tmp/out
+# stdout (one line):
+# {"wasmPath":"/tmp/out/index.wasm","metadataPath":"/tmp/out/index.wasm.json","sizeBytes":1250000,"compilationMs":312,"routes":2}
+```
+
+## Usage: Advanced
+
+```sh
+bunx suaveplan-wasm-compile ./src/plugin/index.ts \
+    --out-dir ./build/wasm \
+    --optimize-for speed \
+    --sourcemaps
+```
+
+```ts
+import { runCli, parseCliArgs } from "@suaveplan/wasm-compiler-javy";
+
+const lines: string[] = [];
+await runCli(["./entry.ts", "--out-dir", "./out"], {
+    stdout: (line) => lines.push(line),
+    stderr: (line) => lines.push("ERR " + line),
+    exit: (code) => { if (code !== 0) throw new Error("nonzero"); },
+});
+```
+
+## API Reference
+
+- `runCli(argv, depsOverride?): Promise<void>` — programmatic entry.
+- `parseCliArgs(argv): CliInvocation` — exported for tests.
+- `isBinInvocation(argv1): boolean` — pure predicate the module-load guard delegates to; matches `cli.js` or `suaveplan-wasm-compile` suffixes.
+- `bootstrap(argv1, argvRest, depsOverride?): Promise<void> | null` — module-load entry. Returns the in-flight `runCli` promise when invoked as the bin script, or `null` when imported as a library.
+- `CliInvocation: { entry, outDir, optimizeFor, sourcemaps, help }`.
+- `CliDeps: { stdout, stderr, exit, compile? }`.
+
+## Implementation Notes
+
+The argv loop is intentionally hand-rolled rather than using a library (`commander`, `yargs`) so the CLI carries zero runtime deps beyond what the compiler itself needs. Each flag handler advances the cursor explicitly to avoid the off-by-one bugs typical of greedy parsers. The CLI does NOT swallow unknown flags — they raise `INVALID_ARGS` with exit code 2 (distinct from `1` reserved for pipeline failures). The bin guard at the bottom of the file checks `process.argv[1]` so importing the module for tests does not auto-execute `runCli` against the test runner's argv. Errors thrown by `compilePluginToWasm` are caught and serialised with their full `context` payload (sanitised by the framework) so operators can reproduce the failure from the JSON alone.