docs: migrate module documentation to single source of truth

Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/development/creating-modules.md

@@ -12,7 +12,7 @@ Creating a new module requires **zero changes** to `main.py`, `registry.py`, or
 # Create module with all directories
 MODULE_NAME=mymodule
 
-mkdir -p app/modules/$MODULE_NAME/{routes/{api,pages},services,models,schemas,templates/$MODULE_NAME/store,static/store/js,locales,tasks}
+mkdir -p app/modules/$MODULE_NAME/{routes/{api,pages},services,models,schemas,templates/$MODULE_NAME/store,static/store/js,locales,tasks,docs}
 
 # Create required files
 touch app/modules/$MODULE_NAME/__init__.py
@@ -156,6 +156,10 @@ app/modules/mymodule/
 │       └── js/
 │           └── mymodule.js
 │
+├── docs/                    # Module documentation (source of truth)
+│   ├── index.md             # Module overview (REQUIRED)
+│   └── ...                  # Additional docs as needed
+│
 ├── locales/                 # Translations (auto-loaded)
 │   ├── en.json
 │   ├── de.json
@@ -538,6 +542,8 @@ python scripts/validate/validate_architecture.py
 - [ ] Create locales (en, de, fr, lu)
 - [ ] Create `config.py` if module needs environment settings (optional)
 - [ ] Create `migrations/versions/` with `__init__.py` files if module has database tables
+- [ ] Create `docs/index.md` with module overview (see [Module Documentation](module-documentation.md))
+- [ ] Create symlink: `ln -s ../../app/modules/$MODULE_NAME/docs docs/modules/$MODULE_NAME`
 - [ ] Run `python scripts/validate/validate_architecture.py`
 - [ ] Test routes are accessible
 
@@ -555,5 +561,6 @@ The framework discovers everything automatically!
 ## Related Documentation
 
 - [Module System](../architecture/module-system.md) - Architecture overview
+- [Module Documentation](module-documentation.md) - Documentation standards
 - [Menu Management](../architecture/menu-management.md) - Sidebar integration
 - [Architecture Rules](architecture-rules.md) - Validation rules

docs/development/module-documentation.md

@@ -0,0 +1,82 @@
+# Module Documentation Standard
+
+This page defines the convention for where documentation lives in the Orion platform.
+
+## Principle: Single Source of Truth
+
+Every module owns its documentation in `app/modules/{name}/docs/`. The top-level `docs/modules/` directory contains **symlinks** to these module docs folders — never duplicate files.
+
+## Module `docs/` Folder (Source of Truth)
+
+Content specific to one module's internals lives inside the module:
+
+```
+app/modules/{name}/docs/
+├── index.md              # Module overview (REQUIRED)
+├── data-model.md         # Entity relationships, schema, field descriptions
+├── api.md                # API endpoints with request/response examples
+├── business-logic.md     # Algorithms, scoring, state machines, workflows
+└── {topic}.md            # Additional topic files as needed
+```
+
+### Required: `index.md`
+
+Every module must have an `index.md` with this structure:
+
+| Section | Content |
+|---------|---------|
+| **Overview table** | Code, classification, dependencies, status |
+| **Features** | Feature list from `definition.py` |
+| **Permissions** | Permission table (if any) |
+| **Data Model** | Brief entity overview or "No database models." |
+| **API Endpoints** | Summary table or "No API endpoints." |
+| **Configuration** | Config keys or "No module-specific configuration." |
+
+### Optional Files
+
+| File | When to Create |
+|------|---------------|
+| `data-model.md` | Module has database models with non-trivial relationships |
+| `api.md` | Module has API routes that need detailed request/response docs |
+| `business-logic.md` | Module has complex algorithms, scoring, or state machines |
+| Additional topic files | As needed (e.g., `scoring.md`, `wallet-integration.md`) |
+
+## Top-Level `docs/`
+
+Cross-cutting, architectural, or multi-module concerns:
+
+| Directory | Content |
+|-----------|---------|
+| `docs/architecture/` | Module system design, cross-module import rules, middleware, multi-tenancy |
+| `docs/development/` | How to create modules, coding standards, migration guides |
+| `docs/deployment/` | Server setup, Docker, CI/CD |
+| `docs/features/` | Feature guides that span multiple modules (e.g., email system touches messaging + tenancy) |
+| `docs/guides/` | End-user / store-admin facing guides |
+
+## Rule of Thumb
+
+> If it's about **how one module works internally**, it goes in the module's `docs/`.
+> If it's about **how modules interact** or **cross-cutting concerns**, it goes in top-level `docs/`.
+
+## How Symlinks Work
+
+The `docs/modules/` directory is populated with symlinks:
+
+```bash
+# Each module gets a symlink
+docs/modules/{name} → ../../app/modules/{name}/docs
+
+# Example
+docs/modules/loyalty → ../../app/modules/loyalty/docs
+docs/modules/billing → ../../app/modules/billing/docs
+```
+
+MkDocs follows these symlinks via its default configuration. When editing module docs, always edit the source files in `app/modules/{name}/docs/` — the symlinks ensure MkDocs picks them up automatically.
+
+## Adding Documentation to a Module
+
+1. Create `app/modules/{name}/docs/index.md` (use existing modules as reference)
+2. Add optional files (`data-model.md`, `api.md`, etc.) as needed
+3. Create the symlink: `ln -s ../../app/modules/{name}/docs docs/modules/{name}`
+4. Add the nav entry in `mkdocs.yml` under the appropriate classification group
+5. Run `mkdocs build --strict` to verify