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/suaveplan-doc-coauthoring/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "suaveplan-doc-coauthoring",
+  "version": "1.0.0",
+  "description": "Structured workflow for co-authoring Suaveplan package documentation"
+}

plugins/suaveplan-doc-coauthoring/skills/doc-coauthoring/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: doc-coauthoring
+description: Co-author module documentation for the Suaveplan monorepo following the module-docs template with simple + advanced examples, 200-word minimum, and 90%+ documentation coverage
+---
+
+# Documentation Co-Authoring for Suaveplan
+
+Write and maintain co-located `.md` documentation files for every implementation module in the Suaveplan monorepo. Documentation is a first-class artifact -- every `.ts` or `.tsx` implementation file must have a corresponding `.md` file in the same directory. This skill follows a 3-stage workflow: context gathering, iterative refinement, and reader testing.
+
+## Documentation Architecture
+
+### File Mapping
+
+```text
+MyClass.ts        ->  MyClass.md          (required)
+my-hook.ts        ->  my-hook.md          (required)
+component.tsx     ->  component.md        (required)
+types.ts          ->  types.md            (required -- for shared type files)
+utils.ts          ->  utils.md            (required)
+index.ts          ->  (not required -- barrel exports only)
+```
+
+### Exclusions (No `.md` Required)
+
+- `.test.ts` / `.test.tsx` -- test files
+- `.spec.ts` -- Playwright E2E files
+- `.types.ts` -- types files within a component directory (shared type files in `types/` DO need docs)
+- `.stories.tsx` -- Storybook stories
+- `constants/index.ts` -- simple constant exports
+
+### Directory Hierarchy
+
+Documentation follows a three-level hierarchy with each level linking down:
+
+```text
+packages/<category>/<sub-category>/<package>/
+  README.md                              # Level 1: Package overview
+  src/
+    <category>/
+      README.md                          # Level 2: Category index
+      <feature>/
+        <feature>.md                     # Level 3: Module documentation
+        <feature>.ts
+```
+
+**Level 1 (Package README)**: Lists all categories with descriptions, quick start, installation.
+**Level 2 (Category README)**: Lists all feature modules with one-line descriptions and links.
+**Level 3 (Module `.md`)**: Full documentation per the template below.
+
+## Template
+
+All module documentation follows `.claude/templates/module-docs.md`. The minimum requirements are:
+
+### Required Sections
+
+1. **Purpose** -- What the module does and why it exists (minimum 2 sentences)
+2. **Features** -- Bullet list of capabilities
+3. **Usage: Basic Example** -- Simple import and usage (the "happy path")
+4. **Usage: Advanced Example** -- Composition, configuration, edge cases
+5. **API Reference** -- Every public export documented with parameters and return types
+6. **Implementation Notes** -- Design decisions, performance considerations, known limitations
+
+### Content Requirements
+
+- **Minimum 200 words** of content (excluding code blocks)
+- **Both simple AND advanced examples** are mandatory in every doc
+- **Code examples must compile** -- use real types and imports from the package
+- **No marketing language** -- state capabilities honestly
+- **No placeholder text** -- every section must contain real content
+- **Update when code changes** -- documentation must stay in sync
+
+## 3-Stage Workflow
+
+### Stage 1: Context Gathering
+
+Before writing documentation, gather full context:
+
+1. **Read the implementation file** -- understand every public export
+2. **Read the types file** -- understand all interfaces and type definitions
+3. **Read the test file** -- understand expected behavior and edge cases
+4. **Read related modules** -- understand how this module fits in the package
+5. **Read the category README** -- understand the broader context
+
+```bash
+# Example: documenting a crypto module
+# Read the implementation
+cat packages/security-stack/crypto/crypto-keys/src/signer/signer.ts
+# Read the types
+cat packages/security-stack/crypto/crypto-keys/src/signer/signer.types.ts
+# Read the tests (understand behavior)
+cat packages/security-stack/crypto/crypto-keys/src/signer/signer.test.ts
+# Read the category README
+cat packages/security-stack/crypto/crypto-keys/src/signer/signer.md
+```
+
+### Stage 2: Iterative Refinement
+
+Write the documentation in passes:
+
+**Pass 1 -- Structure**: Create all section headings and fill in Purpose + Features.
+
+**Pass 2 -- Examples**: Write the Basic Example (simplest correct usage) and Advanced Example (realistic production usage showing composition, error handling, and configuration).
+
+**Pass 3 -- API Reference**: Document every public export:
+
+- Functions: parameters with types, return type, throws, example
+- Classes: constructor, methods, properties
+- Types/Interfaces: every field with description
+- Constants: value, purpose, usage context
+
+**Pass 4 -- Notes**: Add Implementation Notes covering:
+
+- Why this approach was chosen over alternatives
+- Performance characteristics (time/space complexity)
+- Known limitations and workarounds
+- Platform compatibility notes
+
+### Stage 3: Reader Testing
+
+Validate the documentation by asking:
+
+1. **Can a new developer use this module after reading only the Basic Example?**
+2. **Can a senior developer configure advanced use cases from the Advanced Example?**
+3. **Are all public APIs documented so a developer never needs to read source code?**
+4. **Do the code examples actually compile with the correct imports?**
+5. **Is the word count at least 200 words (excluding code blocks)?**
+
+## Example: Complete Module Documentation
+
+```markdown
+# Encryption
+
+## Purpose
+
+Provides symmetric encryption and decryption using AES-256-GCM with authenticated
+encryption. Wraps the Web Crypto API to provide a consistent interface across Node.js
+and browser environments with automatic IV generation and authentication tag handling.
+
+## Features
+
+- AES-256-GCM authenticated encryption
+- Automatic random IV generation per encryption call
+- AEAD (Authenticated Encryption with Associated Data) support
+- Streaming encryption for large payloads
+- Cross-platform (Node.js, browsers, edge runtimes)
+
+## Usage
+
+### Basic Example
+
+\`\`\`typescript
+import { encrypt, decrypt, generateKey } from '@suaveplan/crypto/symmetric/encryption/encryption';
+
+const key = await generateKey();
+const ciphertext = await encrypt(key, 'Hello, world!');
+const plaintext = await decrypt(key, ciphertext);
+// plaintext === 'Hello, world!'
+\`\`\`
+
+### Advanced Example
+
+\`\`\`typescript
+import {
+  encrypt,
+  decrypt,
+  generateKey,
+  type EncryptionOptions,
+} from '@suaveplan/crypto/symmetric/encryption/encryption';
+
+const key = await generateKey();
+
+// Encrypt with associated data for AEAD
+const options: EncryptionOptions = {
+  associatedData: new TextEncoder().encode('metadata-v1'),
+  outputFormat: 'base64',
+};
+
+const ciphertext = await encrypt(key, largePayload, options);
+
+// Decryption must provide the same associated data
+const plaintext = await decrypt(key, ciphertext, {
+  associatedData: options.associatedData,
+  inputFormat: 'base64',
+});
+\`\`\`
+
+## API Reference
+
+### generateKey(): Promise<CryptoKey>
+
+Generates a new AES-256-GCM key using the Web Crypto API.
+
+**Returns:** Promise resolving to a CryptoKey suitable for encrypt/decrypt.
+
+### encrypt(key: CryptoKey, data: string | Uint8Array, options?: EncryptionOptions): Promise<Uint8Array>
+
+Encrypts data using AES-256-GCM.
+
+**Parameters:**
+- `key` -- AES-256-GCM CryptoKey from generateKey()
+- `data` -- Plaintext string or binary data
+- `options` -- Optional EncryptionOptions
+
+**Returns:** Ciphertext with prepended IV (12 bytes) and appended auth tag (16 bytes).
+
+**Throws:** `CryptoError` if key is invalid or encryption fails.
+
+### decrypt(key: CryptoKey, ciphertext: Uint8Array, options?: DecryptionOptions): Promise<string | Uint8Array>
+
+Decrypts AES-256-GCM ciphertext.
+
+**Parameters:**
+- `key` -- Same CryptoKey used for encryption
+- `ciphertext` -- Output from encrypt()
+- `options` -- Optional DecryptionOptions
+
+**Returns:** Original plaintext.
+
+**Throws:** `CryptoError` if authentication fails (tampered data) or key mismatch.
+
+## Implementation Notes
+
+### Design Decisions
+
+- **AES-256-GCM chosen over AES-CBC** because GCM provides authentication
+  (integrity + confidentiality) in a single operation, preventing padding oracle attacks.
+- **IV prepended to ciphertext** so callers do not need to manage IV storage separately.
+  The 12-byte IV is randomly generated per call, making nonce reuse statistically impossible.
+
+### Performance Considerations
+
+- **Time Complexity**: O(n) where n is plaintext length
+- **Memory**: Entire plaintext must fit in memory (use streaming API for large files)
+- **Web Crypto API**: Hardware-accelerated on platforms with AES-NI support
+
+### Known Limitations
+
+- Maximum plaintext size of 64 GiB per encryption call (GCM specification limit)
+- Streaming API requires ReadableStream support (not available in all edge runtimes)
+```
+
+## Verification
+
+Check documentation coverage before marking work complete:
+
+```bash
+# Check documentation coverage for a specific package
+bun run docs:check --filter=@suaveplan/<package-name>
+
+# Target: 90%+ documentation coverage
+```
+
+## Updating Existing Documentation
+
+When implementation code changes:
+
+1. Read the updated implementation file
+2. Identify what changed (new exports, changed signatures, removed APIs)
+3. Update the corresponding `.md` file to reflect changes
+4. Verify examples still compile with the new API
+5. Add a Changelog entry if the change is significant
+
+## Constraints
+
+- **200-word minimum** per documentation file (excluding code blocks)
+- **Simple + Advanced examples** mandatory in every doc
+- **90%+ documentation coverage** per package
+- **Co-located files** -- `MyClass.ts` and `MyClass.md` must be in the same directory
+- **No placeholder text** -- every section must have real content
+- **Code examples must use real imports** -- `@suaveplan/<package>` paths
+- **Follow `.claude/templates/module-docs.md`** template structure
+- **Update docs when code changes** -- stale documentation is a defect
+- **Link between levels** -- README -> Category README -> Module docs
+- Template exclusions: `.test.ts`, `.spec.ts`, `.types.ts`, `.stories.tsx`