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/identity/auth/better-auth-surrealdb/src/schemas/link-fields.md

@@ -0,0 +1,75 @@
+# schemas/link-fields
+
+## Purpose
+
+Zod boundary schema asserting the structural shape of a `LinkFieldMap`. Used
+to validate the optional `linkFields` argument passed to
+`createBetterAuthSurrealAdapter` and to gate any callers that hand-roll their
+own override map at runtime. Validation rejects non-string targets, empty
+keys, and identifiers that would break the generated SurrealQL identifier
+rule (`/^[a-zA-Z_][a-zA-Z0-9_]*$/`).
+
+## Features
+
+- Identifier-rule enforcement on model name, field name, and target table.
+- Empty-string rejection (model/field/target must be `min(1)`).
+- Composable: re-exported as `LinkFieldMapSchema` from `./schemas` and
+  embedded inside `BetterAuthSurrealAdapterOptionsSchema`.
+- Type-level `LinkFieldMapSchemaInput` / `LinkFieldMapSchemaOutput` exports
+  for downstream consumers that derive their own option shapes.
+
+## Usage: Basic
+
+```ts
+import { LinkFieldMapSchema } from "@suaveplan/better-auth-surrealdb/schemas/link-fields";
+
+const parsed = LinkFieldMapSchema.safeParse({
+    session: { userId: "user" },
+});
+if (!parsed.success) throw parsed.error;
+```
+
+## Usage: Advanced
+
+```ts
+import { LinkFieldMapSchema } from "@suaveplan/better-auth-surrealdb/schemas/link-fields";
+
+// Reject non-string targets at the wire boundary
+const bad = LinkFieldMapSchema.safeParse({
+    session: { userId: 5 },
+});
+console.log(bad.success); // false
+
+// Custom map merging
+const merged = LinkFieldMapSchema.parse({
+    ...{ session: { userId: "user" } },
+    ...{ api_key: { userId: "user" } },
+});
+```
+
+## API Reference
+
+- `LinkFieldMapSchema: z.ZodType` — accepts `Record<string, Record<string, string>>`.
+- `LinkFieldMapSchemaInput` — pre-parse type.
+- `LinkFieldMapSchemaOutput` — post-parse type.
+
+## Implementation Notes
+
+The schema uses `z.record(IdentString, z.record(IdentString, IdentString))`.
+Keys go through Zod's `z.record(keySchema, valueSchema)` 4-arg form so the
+identifier check applies to the model/field names as well as the target
+table. Empty-object inputs (`{}`) parse successfully — operators commonly
+pass `linkFields: {}` to disable prefix manipulation entirely.
+
+The `IdentString` schema delegates to `z.string().min(1).regex(...)` so
+the inner regex never has to deal with empty strings (which would slip
+through the regex via the implicit anchored-success path). The error
+message attached to the regex check is human-readable and surfaces in
+`ZodError.issues[i].message` for downstream error reporters, while the
+issue path lets log aggregators pivot on offending fields without
+parsing the message.
+
+Type-level exports `LinkFieldMapSchemaInput` and `LinkFieldMapSchemaOutput`
+are identical in this case (the schema is `transform`-free) but the
+distinction is preserved so future extensions (e.g. coercing aliases to
+canonical table names) can change one without breaking the other.

plugins/document-navigator/docs/identity/auth/better-auth-surrealdb/src/schemas/options.md

@@ -0,0 +1,72 @@
+# schemas/options
+
+## Purpose
+
+Zod boundary schema for `BetterAuthSurrealAdapterOptions`. Drives the runtime
+validation step inside `createBetterAuthSurrealAdapter` so callers cannot
+construct an adapter against a malformed configuration. Failure raises
+`BetterAuthSurrealError(INVALID_INPUT)` carrying the `ZodError` as `cause`,
+which keeps the original field path + issue list available to error
+reporters and OTel adapters.
+
+## Features
+
+- Structural validation of `client` (asserts `query`/`execute` methods).
+- Optional-field gating for `modelToTable`, `idStrategy`, `linkFields`,
+  `logger`.
+- Embedded `LinkFieldMapSchema` reuse — invalid link-field shape surfaces
+  inside the parent schema's `cause.issues`.
+- Identifier-safe id-strategy union `"record-id" | "plain" | "ulid"`.
+
+## Usage: Basic
+
+```ts
+import { BetterAuthSurrealAdapterOptionsSchema } from "@suaveplan/better-auth-surrealdb/schemas/options";
+
+BetterAuthSurrealAdapterOptionsSchema.parse({
+    client: surrealAdapterInstance,
+});
+```
+
+## Usage: Advanced
+
+```ts
+import { BetterAuthSurrealAdapterOptionsSchema } from "@suaveplan/better-auth-surrealdb/schemas/options";
+
+const result = BetterAuthSurrealAdapterOptionsSchema.safeParse({
+    client: surrealAdapterInstance,
+    idStrategy: "ulid",
+    linkFields: { session: { userId: "user" } },
+    modelToTable: (m) => `auth_${m}`,
+});
+
+if (!result.success) {
+    console.error(result.error.issues);
+} else {
+    const opts = result.data; // typed
+}
+```
+
+## API Reference
+
+- `BetterAuthSurrealAdapterOptionsSchema: z.ZodObject` — boundary schema.
+- `BetterAuthSurrealAdapterOptionsInput` — pre-parse type alias.
+
+## Implementation Notes
+
+`client` is validated via `z.custom` with a structural predicate (checks
+`query` and `execute` are both functions) rather than `z.instanceof`,
+because the spec accepts both `SurrealAdapter` instances and bespoke
+`SurrealClientView` objects. The schema strips no keys (the parse pass is
+permissive in case Better-Auth v1.x minor releases extend the contract);
+the factory still narrows by destructuring only the fields it uses.
+
+The validator deliberately returns the originally-supplied client
+reference (Zod's `z.custom` preserves the input identity) rather than
+reconstructing it — this preserves method identity and any private
+state the supplied `SurrealAdapter` holds (connection pool, retry
+counter, OTel context). Failing options surface a `ZodError` with the
+full `issues` array, which the `createBetterAuthSurrealAdapter` factory
+re-raises as `BetterAuthSurrealError(INVALID_INPUT)` with the `ZodError`
+attached as `cause` so downstream log aggregators and OTel exporters get
+the field-level diagnostics without rebuilding them from text.