diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 1605489..4c85801 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -12,6 +12,7 @@
 * [Docker Deployment](getting-started/docker-deployment.md)
 * [Environment Variables](getting-started/environment-variables.md)
 * [Building from Source](getting-started/building-from-source.md)
+* [Versioning & Compatibility](getting-started/versioning.md)
 
 # SDK
 
diff --git a/docs/getting-started/docker-deployment.md b/docs/getting-started/docker-deployment.md
index 6d0da56..ef53900 100644
--- a/docs/getting-started/docker-deployment.md
+++ b/docs/getting-started/docker-deployment.md
@@ -6,9 +6,11 @@
 docker run -d -p 3000:3000 \
   -e PORTAL__AUTH__AUTH_TOKEN=your-secret-token \
   -e PORTAL__NOSTR__PRIVATE_KEY=your-nostr-private-key-hex \
-  getportal/sdk-daemon:latest
+  getportal/sdk-daemon:0.3.0
 ```
 
+> **Tip:** pin a specific version in production (e.g. `0.3.0`) rather than `:latest` to avoid unexpected updates. The image is multi-arch (amd64 + arm64) — Docker pulls the right variant automatically. See [Versioning & Compatibility](versioning.md).
+
 Check: curl http://localhost:3000/health, curl http://localhost:3000/version. WebSocket API: ws://localhost:3000/ws (auth required).
 
 ## Docker Compose
@@ -18,7 +20,7 @@ docker-compose.yml:
 ```yaml
 services:
   portal:
-    image: getportal/sdk-daemon:latest
+    image: getportal/sdk-daemon:0.3.0
     ports: ["3000:3000"]
     environment:
       - PORTAL__AUTH__AUTH_TOKEN=${PORTAL__AUTH__AUTH_TOKEN}
@@ -66,4 +68,4 @@ Use HTTPS and a reverse proxy in production; don’t commit secrets.
 
 ---
 
-- [Environment variables](environment-variables.md) · [SDK](../sdk/installation.md) · [Building from source](building-from-source.md)
+- [Environment variables](environment-variables.md) · [SDK](../sdk/installation.md) · [Building from source](building-from-source.md) · [Versioning](versioning.md)
diff --git a/docs/getting-started/versioning.md b/docs/getting-started/versioning.md
new file mode 100644
index 0000000..6736dfb
--- /dev/null
+++ b/docs/getting-started/versioning.md
@@ -0,0 +1,58 @@
+# Versioning & Compatibility
+
+Portal follows a simple versioning policy designed to make compatibility obvious.
+
+## Version scheme
+
+All Portal components use **semantic versioning** (`major.minor.patch`):
+
+| Component | Package |
+|-----------|---------|
+| `portal-rest` (SDK Daemon) | Docker: `getportal/sdk-daemon` |
+| TypeScript SDK | npm: `portal-sdk` |
+| Java SDK | JitPack: `com.github.PortalTechnologiesInc:java-sdk` |
+
+## Compatibility rule
+
+**`major.minor` must match between the SDK and the SDK Daemon. The patch version is independent.**
+
+In other words:
+
+- SDK `0.3.0` ↔ SDK Daemon `0.3.0` ✅
+- SDK `0.3.4` ↔ SDK Daemon `0.3.1` ✅ (patch is irrelevant)
+- SDK `0.3.x` ↔ SDK Daemon `0.4.x` ❌ (minor mismatch)
+
+Patch releases contain bug fixes and non-breaking improvements within the same `major.minor`. You can update the SDK or the Daemon independently as long as `major.minor` stays the same.
+
+## Upgrading
+
+When a new `major.minor` version is released:
+
+1. Update your SDK dependency to the matching version.
+2. Update the Docker image tag to the matching version.
+3. Check the [CHANGELOG](../../CHANGELOG.md) for breaking changes.
+
+**Example — upgrading to 0.4.0:**
+
+```bash
+# Docker
+docker pull getportal/sdk-daemon:0.4.0
+```
+
+```bash
+# npm
+npm install portal-sdk@0.4.0
+```
+
+```groovy
+// Gradle
+implementation 'com.github.PortalTechnologiesInc:java-sdk:0.4.0'
+```
+
+## Current versions
+
+| Component | Version |
+|-----------|---------|
+| SDK Daemon (`getportal/sdk-daemon`) | `0.3.0` |
+| TypeScript SDK (`portal-sdk`) | `0.3.0` |
+| Java SDK | `0.3.0` |
diff --git a/docs/sdk/installation.md b/docs/sdk/installation.md
index 05067f4..c979f7f 100644
--- a/docs/sdk/installation.md
+++ b/docs/sdk/installation.md
@@ -50,7 +50,7 @@ repositories {
     maven { url 'https://jitpack.io' }
 }
 dependencies {
-    implementation 'com.github.PortalTechnologiesInc:java-sdk:0.2.1'
+    implementation 'com.github.PortalTechnologiesInc:java-sdk:0.3.0'
 }
 ```
 
@@ -64,7 +64,7 @@ dependencies {
 <dependency>
     <groupId>com.github.PortalTechnologiesInc</groupId>
     <artifactId>java-sdk</artifactId>
-    <version>0.2.1</version>
+    <version>0.3.0</version>
 </dependency>
 ```
 
@@ -110,4 +110,8 @@ Use sendCommand(request, (response, err) -> { ... }) for commands. Request/respo
 
 ---
 
+> **Compatibility:** the SDK `major.minor` version must match the SDK Daemon (`getportal/sdk-daemon`) `major.minor`. Patch versions are independent. See [Versioning & Compatibility](../getting-started/versioning.md).
+
+---
+
 - [Basic Usage](basic-usage.md) · [Configuration](configuration.md) · [Guides](../guides/authentication.md)