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-plugin-site/src/routes/private-routes.md

@@ -0,0 +1,53 @@
+# `routes/private-routes.ts`
+
+## Purpose
+
+Builds the authenticated Hono route tree for site CRUD and domain management. The factory is intentionally auth-agnostic — the suaveplan convention is that the host application composes auth middleware (`requireAuth()` from `@suaveplan/api-plugin-auth` or any equivalent) at the prefix where this router is mounted. Decoupling auth from the route factory keeps the package usable by any consumer (e.g. a future GraphQL gateway, an admin CLI) without forcing a hard dependency on a specific auth plugin.
+
+## Features
+
+- `POST /sites` — create.
+- `PATCH /sites/{id}` — update name / settings.
+- `POST /sites/{id}/domains` — add domain.
+- `DELETE /sites/{id}/domains` — remove domain.
+- OpenAPI schemas embedded inline via `@hono/zod-openapi` so the generated spec is the contract.
+- Errors propagate as `SiteError` (caught and rendered by the host's global error middleware).
+
+## Usage: Basic
+
+```ts
+import { createPrivateSiteRoutes } from "@suaveplan/api-plugin-site/routes/private-routes";
+
+const privateRouter = createPrivateSiteRoutes({ siteService });
+app.use("/api/v1", requireAuth());
+app.route("/api/v1", privateRouter);
+```
+
+## Usage: Advanced
+
+```ts
+// Layer additional rate-limit + audit middleware on top.
+const privateRouter = createPrivateSiteRoutes({ siteService });
+app.use("/admin", requireAuth(), rateLimit({ key: "site-mutations" }));
+app.route("/admin", privateRouter);
+```
+
+## API Reference
+
+- `interface PrivateSiteRoutesDeps` — `siteService`.
+- `createPrivateSiteRoutes(deps: PrivateSiteRoutesDeps): OpenAPIHono`.
+
+## Recommended middleware
+
+Write routes benefit most from layered rate-limit + audit middleware. The site plugin ships the `MIDDLEWARE_RECOMMENDATIONS` constant (see `src/integration/middleware-recommendations.md`) describing the recommended ceiling and audit category for this group:
+
+- **Rate-limit**: `30 req / 60s` on the `/sites/*` path pattern (`private:write` group). Writes are rare per tenant and warrant the tightest ceiling; this protects the database from runaway clients without inconveniencing legitimate operators.
+- **Audit category**: `data.mutation`. Every successful or failed write produces one `AuditEvent` in the host's configured `AuditStorageAdapter`. Combine with `enableChainIntegrity: true` for a tamper-evident trail.
+
+The recommended layering order — audit OUTERMOST, rate-limit MIDDLE, site routes INNERMOST — is documented end-to-end in `docs/middleware-integration.md` and proven by `src/integration/middleware-composition.integration.test.ts`. The site plugin does not bind either middleware itself; composition stays in the host via the Hono `app.use(prefix, middleware)` pattern.
+
+## Implementation Notes
+
+- The factory accepts a single deps object so future additions (audit, event bus) stay non-breaking.
+- All bodies are Zod-validated via `@hono/zod-openapi` — invalid input is rejected before reaching the service.
+- The "remove domain" endpoint uses a body (not a path segment) so callers can submit the canonical-cased domain string and so the operation can be batched in future without an additional route shape.

plugins/document-navigator/docs/api-stack/api/api-plugin-site/src/routes/public-routes.md

@@ -0,0 +1,43 @@
+# `routes/public-routes.ts`
+
+## Purpose
+
+Builds the public (no-auth) Hono route tree that the plugin mounts under the configured `routePrefix`. The two endpoints exposed here are the entrypoints used by edge / SSR consumers that haven't yet authenticated — domain resolution drives multi-tenant routing decisions at request ingress, and the public-info endpoint surfaces a santised view of the site (theme + feature flags) so client bundles can render branded shells without leaking push config or secrets.
+
+Routes are wired through `@hono/zod-openapi` so the OpenAPI document the host app exposes is automatically populated from the same Zod schemas the service layer validates against.
+
+## Features
+
+- `GET /sites/resolve/{domain}` — resolves a domain to a site + organization envelope.
+- `GET /sites/{id}/public` — returns the `SitePublicInfo` projection.
+- Both routes leverage the canonical `SiteSchema` / `SitePublicInfoSchema` for OpenAPI typing.
+- Failures bubble up as `SiteError` so the host-app error middleware can map them to RFC 7807 / structured envelopes consistently with other plugins.
+
+## Usage: Basic
+
+```ts
+import { createPublicSiteRoutes } from "@suaveplan/api-plugin-site/routes/public-routes";
+
+const publicRouter = createPublicSiteRoutes({ siteService, domainResolver });
+app.route("/api", publicRouter);
+```
+
+## Usage: Advanced
+
+```ts
+// Mount under a custom prefix and layer additional middleware.
+const publicRouter = createPublicSiteRoutes({ siteService, domainResolver });
+app.use("/v1", rateLimitMiddleware);
+app.route("/v1", publicRouter);
+```
+
+## API Reference
+
+- `interface PublicSiteRoutesDeps` — `siteService`, `domainResolver`.
+- `createPublicSiteRoutes(deps: PublicSiteRoutesDeps): OpenAPIHono`.
+
+## Implementation Notes
+
+- The resolve route always returns 200 with `success: false` on miss — this mirrors the upstream contract so an existing consumer's redirect logic does not have to swap between 200 and 404.
+- The public-info route DOES throw `SITE.SITE_NOT_FOUND` on miss, because the route is the integration boundary between "lookup" and "render" — a 404 here is the conventional signal to the upstream caller.
+- The conditional spread (`...(site.slug !== undefined && {...})`) keeps the JSON payload tight by omitting absent optionals rather than emitting `null`.