diff --git a/MODULE_SPEC.md b/MODULE_SPEC.md
new file mode 100644
index 0000000..b160a81
--- /dev/null
+++ b/MODULE_SPEC.md
@@ -0,0 +1,38 @@
+# rFiles — File Sharing
+
+**Module ID:** `rfiles`
+**Domain:** `rfiles.online`
+**Version:** 0.1.0
+**Framework:** Django 5.2 / DRF / PostgreSQL / Celery / Redis
+**Status:** Active
+
+## Purpose
+
+Secure file sharing with space-based access control and asynchronous processing. Uses Django REST Framework with EncryptID JWT authentication. Celery workers handle background tasks (file processing, indexing).
+
+## Data Model
+
+Django models (PostgreSQL). SharedSpaces, files, users. Includes `visibility` and `owner_did` fields on SharedSpace.
+
+## Permission Model
+
+| Capability | Required SpaceRole | Description |
+|-----------|-------------------|-------------|
+| `view_files` | VIEWER | Browse and download files |
+| `upload_file` | PARTICIPANT | Upload new files |
+| `manage_own_files` | PARTICIPANT | Rename/delete own files |
+| `manage_any_files` | MODERATOR | Edit/delete any file |
+| `configure_storage` | ADMIN | Space settings, storage quotas |
+
+**Current Auth:** EncryptID JWT via Django middleware + DRF `SpacePermission` class. Space visibility already implemented.
+
+## Canvas Integration
+
+Future: `folk-file` shape for file preview cards on canvas.
+
+## Migration Plan
+
+1. Already has EncryptID auth + space visibility
+2. Import Python `SpaceRole` from `encryptid-sdk/src/python/roles.py`
+3. Add `has_capability()` checks in DRF permission classes
+4. Add membership table for explicit role assignments