diff --git a/src/content/docs/architecture.md b/src/content/docs/architecture.md
index 56ee1c2..f51a2cc 100644
--- a/src/content/docs/architecture.md
+++ b/src/content/docs/architecture.md
@@ -110,7 +110,7 @@ sequenceDiagram
 
 ### Storage Layer
 
-**[Homeservers](/explore/pubkycore/homeserver/)** store user data in a key-value format over HTTP/HTTPS.
+**[Homeservers](/explore/pubkycore/homeserver/)** store user data as files addressed by paths over HTTP/HTTPS.
 
 **Architecture:**
 
@@ -119,11 +119,11 @@ flowchart LR
     User1[User 1] --> HS1[Homeserver A]
     User2[User 2] --> HS1
     User3[User 3] --> HS2[Homeserver B]
-    User4[User 4] --> HS3[Homeserver C]
     
-    HS1 --> DB1[(PostgreSQL)]
-    HS2 --> DB2[(LMDB)]
-    HS3 --> DB3[(Files)]
+    HS1 --> FS1[(User files)]
+    HS1 --> PG1[(PostgreSQL metadata)]
+    HS2 --> FS2[(User files)]
+    HS2 --> PG2[(PostgreSQL metadata)]
 ```
 
 **Key Properties:**
diff --git a/src/content/docs/contributing.md b/src/content/docs/contributing.md
index 84c7f94..fb59f31 100644
--- a/src/content/docs/contributing.md
+++ b/src/content/docs/contributing.md
@@ -190,7 +190,7 @@ cargo build
 # Run tests
 cargo test
 
-# Run homeserver locally
+# Run homeserver locally (requires PostgreSQL and database_url in config)
 cargo run --bin pubky-homeserver
 
 # Format code
diff --git a/src/content/docs/explore/pubkycore/api.md b/src/content/docs/explore/pubkycore/api.md
index b9487e4..25f9b79 100644
--- a/src/content/docs/explore/pubkycore/api.md
+++ b/src/content/docs/explore/pubkycore/api.md
@@ -356,7 +356,7 @@ Returns the user count, the disabled-user count, total disk usage in MB, signup-
   "public_key": "8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo",
   "pkarr_pubky_address": null,
   "pkarr_icann_domain": "homeserver.example.com",
-  "version": "0.7.0"
+  "version": "0.8.0"
 }
 ```
 
diff --git a/src/content/docs/explore/pubkycore/homeserver.md b/src/content/docs/explore/pubkycore/homeserver.md
index 10d831a..50a6901 100644
--- a/src/content/docs/explore/pubkycore/homeserver.md
+++ b/src/content/docs/explore/pubkycore/homeserver.md
@@ -44,7 +44,7 @@ See [Security Model](/explore/pubkycore/security-model/) for the full trust anal
 
 > **Note:** Production deployment guides are not yet available. Easy deployment packages (Umbrel, apt, docker, start9) are under development.
 
-For local development and testing:
+For local development and testing, start PostgreSQL and configure `database_url`, then run:
 
 ```bash
 cargo run -p pubky-homeserver
@@ -58,7 +58,7 @@ cargo run -p pubky-testnet
 
 ### Embedded Postgres
 
-Since v0.7.0, the testnet supports an optional embedded Postgres mode via the `embedded-postgres` feature flag. This allows fully self-contained test environments without requiring an external database:
+The testnet can start embedded Postgres via the `embedded-postgres` feature flag. This keeps local test environments self-contained without requiring an external database:
 
 ```bash
 cargo run -p pubky-testnet --features embedded-postgres
diff --git a/src/content/docs/explore/pubkycore/introduction.md b/src/content/docs/explore/pubkycore/introduction.md
index b6ad0bb..e330dcc 100644
--- a/src/content/docs/explore/pubkycore/introduction.md
+++ b/src/content/docs/explore/pubkycore/introduction.md
@@ -37,7 +37,7 @@ A production-ready server application that:
 - Provides RESTful HTTP API
 - Handles authentication and sessions
 - Publishes to [PKARR](/explore/pubkycore/pkarr/introduction/) for discovery
-- Supports multiple persistence backends (Files, LMDB, SQL)
+- Stores user files separately from PostgreSQL-backed homeserver metadata
 - Includes admin and metrics endpoints
 
 ### 3. SDK (Software Development Kit)
@@ -82,7 +82,7 @@ Pubky Core's distributed architecture provides user autonomy through credible ex
 - **Docker support**: Easy deployment and testing
 
 ### Production-Ready
-- **Multiple persistence backends**: Choose between Files, LMDB, or SQL
+- **PostgreSQL-backed metadata**: Homeservers store user files separately while PostgreSQL tracks users, quotas, sessions, and events
 - **Rate limiting**: Built-in DDoS protection
 - **Metrics and monitoring**: Prometheus-compatible metrics
 - **Admin API**: Server management and diagnostics
@@ -147,10 +147,11 @@ See [SDK Documentation](/explore/pubkycore/sdk/) for complete guides.
 ### Run Local Homeserver
 
 **Using Cargo:**
+Start PostgreSQL and configure `database_url` before running a standalone Homeserver:
 ```bash
 git clone https://github.com/pubky/pubky-core
 cd pubky-core/pubky-homeserver
-cargo run
+cargo run -- --data-dir=~/.pubky
 ```
 
 **Using Docker:**
@@ -257,7 +258,7 @@ For [Synonym](https://synonym.to/) as lead of this project, the goal is to:
 - ✅ JavaScript/WASM bindings stable
 - ✅ Authentication system complete
 - ✅ Event streaming SDK (SSE-based, single and multi-user)
-- ✅ Multiple persistence backends
+- ✅ User file storage on Homeservers, with PostgreSQL-backed metadata
 
 **Active Development:**
 - 🚧 Mobile native bindings (iOS/Android)
diff --git a/src/content/docs/explore/pubkycore/sdk.md b/src/content/docs/explore/pubkycore/sdk.md
index 0511d26..0c2880a 100644
--- a/src/content/docs/explore/pubkycore/sdk.md
+++ b/src/content/docs/explore/pubkycore/sdk.md
@@ -322,8 +322,8 @@ For development, run a local Homeserver:
 git clone https://github.com/pubky/pubky-core
 cd pubky-core
 
-# Run testnet
-cargo run --bin pubky-testnet
+# Run testnet with embedded PostgreSQL
+cargo run -p pubky-testnet --features embedded-postgres
 ```
 
 Then connect your app to `http://localhost:15411`.
diff --git a/src/content/docs/explore/technologies/pubky-cli.md b/src/content/docs/explore/technologies/pubky-cli.md
index fb163b5..f4cc0d1 100644
--- a/src/content/docs/explore/technologies/pubky-cli.md
+++ b/src/content/docs/explore/technologies/pubky-cli.md
@@ -213,7 +213,7 @@ echo "User onboarded successfully!"
 
 Test Homeserver functionality without building custom clients:
 ```bash
-# Start local homeserver
+# Start local homeserver (requires PostgreSQL and database_url in config)
 cargo run -p pubky-homeserver -- --data-dir ~/.pubky
 
 # Test with CLI
diff --git a/src/content/docs/getting-started.md b/src/content/docs/getting-started.md
index 38ce508..4b12205 100644
--- a/src/content/docs/getting-started.md
+++ b/src/content/docs/getting-started.md
@@ -113,11 +113,11 @@ cd ios && pod install  # iOS only
 
 See the [Pubky Docker documentation](/explore/technologies/pubky-docker/) for setup instructions, port mappings, and configuration options.
 
-**Alternative**: Run just a Homeserver:
+**Alternative**: Run just a Homeserver. Start PostgreSQL and configure `database_url` first; see the [Homeserver documentation](/explore/pubkycore/homeserver/) for details:
 ```bash
 git clone https://github.com/pubky/pubky-core
 cd pubky-core/pubky-homeserver
-cargo run
+cargo run -- --data-dir=~/.pubky
 ```
 
 ### Step 3: Build Your First App
diff --git a/src/content/docs/glossary.md b/src/content/docs/glossary.md
index b52c2ba..6080aeb 100644
--- a/src/content/docs/glossary.md
+++ b/src/content/docs/glossary.md
@@ -39,7 +39,7 @@ Protocol for encrypting DNS queries using HTTPS, preventing surveillance and tam
 ## H
 
 **[Homeserver](/explore/pubkycore/homeserver/)**
-A web server that stores user data in a key-value format. Users can run their own or choose any provider. Data is stored per public key and accessed via HTTP/HTTPS.
+A web server that stores user data as files addressed by paths. Internally, PostgreSQL tracks metadata such as users, quotas, sessions, and events. Users can run their own or choose any provider. Data is stored per public key and accessed via HTTP/HTTPS.
 
 **[Homegate](/explore/technologies/homegate/)**
 A signup verification service for Homeservers, providing SMS and Lightning Network payment verification to prevent spam while preserving privacy.