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-schemas/src/admin/health.md

@@ -0,0 +1,85 @@
+# health
+
+## Purpose
+
+Defines Zod schemas for the admin health check endpoint (`GET /admin/health`). The health endpoint exposes a structured view of the service's operational status — both an aggregate roll-up and per-subsystem detail — so that load balancers, container orchestrators, and monitoring dashboards can make informed routing and alerting decisions without parsing unstructured text responses.
+
+## Features
+
+- `HealthStatus` enum schema — `"ok" | "degraded" | "down"` covering the full range of operational states
+- `HealthCheck` object schema — per-subsystem check with status, optional latency measurement, and optional message
+- `AdminHealthOutput` schema — aggregate `status` plus a `checks` record keyed by subsystem name (non-empty keys)
+- `latencyMs` validated as a non-negative number — negative latency is not physically meaningful
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { AdminHealthOutput } from "@suaveplan/api-schemas/admin";
+
+const health = AdminHealthOutput.parse({
+  status: "ok",
+  checks: {
+    database: { status: "ok", latencyMs: 3 },
+    cache: { status: "ok", latencyMs: 1 },
+  },
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { AdminHealthOutput, HealthStatus } from "@suaveplan/api-schemas/admin";
+
+async function collectHealth(): Promise<AdminHealthOutput> {
+  const dbLatency = await measureDbPing();
+  const cacheLatency = await measureCachePing();
+
+  const checks = {
+    database: { status: dbLatency < 100 ? "ok" : "degraded" as HealthStatus, latencyMs: dbLatency },
+    cache: { status: cacheLatency < 10 ? "ok" : "degraded" as HealthStatus, latencyMs: cacheLatency },
+  };
+
+  const anyDown = Object.values(checks).some((c) => c.status === "down");
+  const anyDegraded = Object.values(checks).some((c) => c.status === "degraded");
+  const status: HealthStatus = anyDown ? "down" : anyDegraded ? "degraded" : "ok";
+
+  return AdminHealthOutput.parse({ status, checks });
+}
+```
+
+## API Reference
+
+### `HealthStatus`
+
+Zod enum: `"ok" | "degraded" | "down"`.
+
+**Type export:** `type HealthStatus = z.infer<typeof HealthStatus>`
+
+### `HealthCheck`
+
+Zod object schema — single subsystem check result.
+
+| Field       | Type                 | Description                                      |
+|-------------|----------------------|--------------------------------------------------|
+| `status`    | `HealthStatus`       | Status of this individual check                  |
+| `latencyMs` | `number` (≥ 0)       | Round-trip latency; omit when not measured       |
+| `message`   | `string`             | Optional human-readable context                  |
+
+**Type export:** `type HealthCheck = z.infer<typeof HealthCheck>`
+
+### `AdminHealthOutput`
+
+Zod object schema — health endpoint response.
+
+| Field    | Type                                | Description                                   |
+|----------|-------------------------------------|-----------------------------------------------|
+| `status` | `HealthStatus`                      | Aggregate service status                      |
+| `checks` | `Record<string, HealthCheck>`       | Keyed map of subsystem check results          |
+
+**Type export:** `type AdminHealthOutput = z.infer<typeof AdminHealthOutput>`
+
+## Implementation Notes
+
+The aggregate `status` should be the worst of all individual check statuses — if any check is `"down"` the aggregate should be `"down"`; if any is `"degraded"` and none are `"down"` the aggregate should be `"degraded"`. This roll-up logic belongs in the route handler, not the schema. The `checks` record uses `z.record(z.string().min(1), ...)` to enforce non-empty subsystem names, preventing accidental empty-string keys that would make the map structure ambiguous.

plugins/document-navigator/docs/api-stack/api/api-schemas/src/admin/ping.md

@@ -0,0 +1,63 @@
+# ping
+
+## Purpose
+
+Provides Zod schemas for the admin ping endpoint (`GET /admin/ping`). The ping endpoint is the simplest possible health indicator — it verifies that the server is alive, the request pipeline is functional, and the clock is ticking. These schemas are used by server route handlers, monitoring systems, and the OpenAPI generator to define the contract for this sentinel endpoint.
+
+## Features
+
+- `AdminPingInput` schema — empty object (no input required); useful as a typed placeholder for framework plugins that require a body schema
+- `AdminPingOutput` schema — `{pong: true, timestamp}` where `pong` is a typed literal and `timestamp` is an ISO 8601 string with timezone offset
+- `pong: z.literal(true)` ensures TypeScript narrows the field to `true`, not `boolean`
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { AdminPingOutput } from "@suaveplan/api-schemas/admin";
+
+const response = AdminPingOutput.parse({
+  pong: true,
+  timestamp: new Date().toISOString(),
+});
+// → { pong: true, timestamp: "2024-06-01T12:00:00.000Z" }
+```
+
+## Usage: Advanced Example
+
+```ts
+import { AdminPingInput, AdminPingOutput } from "@suaveplan/api-schemas/admin";
+
+// Route handler using both input and output schemas
+async function handlePing(_rawBody: unknown): Promise<AdminPingOutput> {
+  AdminPingInput.parse(_rawBody); // no-op for empty body, ensures shape check
+  return AdminPingOutput.parse({
+    pong: true,
+    timestamp: new Date().toISOString(),
+  });
+}
+```
+
+## API Reference
+
+### `AdminPingInput`
+
+Zod object schema — empty input (no fields).
+
+**Type export:** `type AdminPingInput = z.infer<typeof AdminPingInput>`
+
+### `AdminPingOutput`
+
+Zod object schema — ping response.
+
+| Field       | Type                            | Description                              |
+|-------------|----------------------------------|------------------------------------------|
+| `pong`      | `true` (literal)                | Confirms endpoint reachability           |
+| `timestamp` | `string` (ISO 8601 with offset) | Server clock time at request processing  |
+
+**Type export:** `type AdminPingOutput = z.infer<typeof AdminPingOutput>`
+
+## Implementation Notes
+
+The `pong` field uses `z.literal(true)` rather than `z.boolean()` to make the success state an unambiguous type-level fact — TypeScript will infer `pong: true` not `pong: boolean`, enabling exhaustiveness checks. The `timestamp` is included so monitoring tools can detect clock skew between the client and server without an additional round-trip to a time endpoint. The `AdminPingInput` empty-object schema exists to keep route plugin signatures uniform: every endpoint has both an input and an output schema.

plugins/document-navigator/docs/api-stack/api/api-schemas/src/admin/status.md

@@ -0,0 +1,60 @@
+# status
+
+## Purpose
+
+Defines the Zod schema for the admin status endpoint (`GET /admin/status`), which exposes static deployment metadata for debugging, support, and operational dashboards. Unlike the health endpoint, the status endpoint does not probe live dependencies — it reports the deployed application version, process uptime, environment name, and Node.js runtime version. These schemas ensure the response is consistently structured across all environments.
+
+## Features
+
+- `AdminStatusOutput` schema — `{version, uptime, environment, nodeVersion}` with strict Zod validation
+- `uptime` validated as a non-negative number representing seconds since process start
+- All string fields validated as non-empty to prevent blank deployment metadata
+- Full TypeScript inference via `z.infer<>` — no manual interface duplication
+- Zod v4 compatible
+
+## Usage: Basic Example
+
+```ts
+import { AdminStatusOutput } from "@suaveplan/api-schemas/admin";
+
+const status = AdminStatusOutput.parse({
+  version: "1.0.0",
+  uptime: 86400,
+  environment: "production",
+  nodeVersion: "v22.0.0",
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { AdminStatusOutput } from "@suaveplan/api-schemas/admin";
+
+function buildStatus(startTime: number): AdminStatusOutput {
+  return AdminStatusOutput.parse({
+    version: process.env["APP_VERSION"] ?? "unknown",
+    uptime: Math.floor((Date.now() - startTime) / 1000),
+    environment: process.env["NODE_ENV"] ?? "development",
+    nodeVersion: process.version,
+  });
+}
+```
+
+## API Reference
+
+### `AdminStatusOutput`
+
+Zod object schema — status endpoint response.
+
+| Field         | Type             | Description                                         |
+|---------------|------------------|-----------------------------------------------------|
+| `version`     | `string` (min 1) | Semantic version of the deployed application        |
+| `uptime`      | `number` (≥ 0)   | Seconds the process has been running                |
+| `environment` | `string` (min 1) | Deployment environment (production, staging, etc.)  |
+| `nodeVersion` | `string` (min 1) | Node.js runtime version string                      |
+
+**Type export:** `type AdminStatusOutput = z.infer<typeof AdminStatusOutput>`
+
+## Implementation Notes
+
+The `uptime` field uses floating-point seconds rather than milliseconds for human readability — `86400` (one day) is far more legible than `86400000`. The `nodeVersion` field is included so support engineers can quickly confirm whether a production issue is related to a known Node.js version bug without needing shell access. In Bun environments, `process.version` still reports the Node.js compatibility version rather than the Bun version; populate `nodeVersion` accordingly.