diff --git a/apps/docs/content/features/backup.mdx b/apps/docs/content/features/backup.mdx
index e8abbe8d..0a2331c6 100644
--- a/apps/docs/content/features/backup.mdx
+++ b/apps/docs/content/features/backup.mdx
@@ -7,7 +7,7 @@ Zerops provides an automated, secure backup system for supported services. This
 
 ## Supported Services
 
-Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/manage#backups), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/backup).
+Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/manage#backups), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/manage#backups).
 
 ## Managing Backups in the UI
 
diff --git a/apps/docs/content/references/import.mdx b/apps/docs/content/references/import.mdx
index 84c9e721..e2d9d525 100644
--- a/apps/docs/content/references/import.mdx
+++ b/apps/docs/content/references/import.mdx
@@ -128,7 +128,7 @@ services:
     override: false
   # REQUIRED. Name of your other service
   - hostname: teststorage1
-    type: shared-storage
+    type: shared-storage:ha
     ...
 ```
 </DropdownItem>
@@ -322,7 +322,7 @@ services:
 
   # A second, simpler service example
   - hostname: teststorage1
-    type: shared-storage
+    type: shared-storage:ha
 ```
 
 This example includes all possible configuration options for Zerops services. Not all options are required or applicable to every service type. The example shows two services in the same YAML file: a fully configured Node.js API service and a simpler static frontend service.
@@ -696,6 +696,8 @@ services:
 
 The `mount:` parameter allows you to mount a shared storage (which should be created inside the project) to the service.
 
+The `buildFromGit` requirement exists because an import without it only creates an empty service shell with nothing deployed yet, so there is nothing to mount the storage into. With `buildFromGit`, the import also builds and deploys the repository, and the mount is applied to the deployed service. If you import a service without `buildFromGit`, deploy your application first and then connect the shared storage [in the GUI](/shared-storage/how-to/connect).
+
 ### Service Nginx Configuration
 
 The nginx configuration defines the nginx settings for the service.
diff --git a/apps/docs/content/shared-storage/how-to/backup.mdx b/apps/docs/content/shared-storage/how-to/backup.mdx
deleted file mode 100644
index 524e1dc2..00000000
--- a/apps/docs/content/shared-storage/how-to/backup.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Backup Shared Storage
-description: Learn how to backup and restore your Shared Storage data in Zerops.
----
-
-Zerops provides automated data backup for Shared Storage services with full encryption and flexible management options.
-
-For general backup information including configuration, scheduling, and management options, see the [Zerops Backups](/features/backup) documentation, which covers:
-- Backup scheduling and retention policies
-- Tagging system and storage quotas
-- Manual backup creation and CLI tools
-- Security and encryption details
-
-## Shared Storage Backup Format
-
-Shared Storage backups are created using tar archival:
-
-- **Format**: `.tar.gz` (archive of directory contents)
-- **Tooling**: `tar`
-- **Content**: Compresses the entire shared volume (`/mnt/<volume>`)
-- **Storage**: Encrypted and stored in isolated object storage
-
-### Restoring Backups
-
-To restore a Shared Storage backup: Download the backup file (`.tar.gz`) from the Zerops UI, extract the archive, and upload the contents back to your Shared Storage.
-
-## Best Practices
-
-For Shared Storage backups:
-- Regularly clean up unnecessary files from your Shared Storage to reduce backup size
-- Create manual backups with protected tags before major file operations or migrations
-- Consider adjusting your backup frequency for optimal storage usage
-- Test your restore process periodically to ensure data integrity
-
-For additional best practices and troubleshooting, refer to the [main backup documentation](/features/backup).
\ No newline at end of file
diff --git a/apps/docs/content/shared-storage/how-to/connect.mdx b/apps/docs/content/shared-storage/how-to/connect.mdx
index b1d3af6c..faf05110 100644
--- a/apps/docs/content/shared-storage/how-to/connect.mdx
+++ b/apps/docs/content/shared-storage/how-to/connect.mdx
@@ -1,43 +1,74 @@
 ---
-title: Connect shared storage to a runtime service
-description: Learn how to connect shared storage to other services in Zerops.
+title: Connect & mount shared storage
+description: Learn how to connect shared storage to runtime services in Zerops and how the mount behaves.
 ---
 
-import GroupCards from '@site/src/components/GroupCards';
+This page covers how to connect an existing shared storage to runtime services, how to disconnect it, and how the mount behaves inside your containers.
 
-This page covers how to connect an existing shared storage to runtime services and how to disconnect services when needed.
+## How the mount behaves
 
-## In Zerops GUI
+Once a shared storage is connected to a runtime service, Zerops mounts it at `/mnt/<storage-hostname>` in the runtime containers. For example, `/mnt/teststorage` for a `teststorage` shared storage:
 
-### Connect a new shared storage
+<figure style={{ textAlign: 'center', margin: '1rem 0' }}>
+  <img
+    src="/img/screenshots/connect_shared_storage_2.png"
+    alt="Mounted shared storage in the file browser"
+    width="100%"
+    height="auto"
+  />
+</figure>
+
+- The content is shared among **all containers** of the connected runtime service; if you connect multiple runtime services, they all see the same content
+- Multiple storages can be mounted to a single service (e.g. `/mnt/files1`, `/mnt/files2`)
+- The mount point is owned by the `zerops` user and group (no sudo required)
+- Mounting removes any existing content of the mount directory
+- The mount is only available in runtime containers, not during build and prepare runtime phases
+- The mount process logs its standard output and error to the runtime service logs (tagged `zerops-mount-<service-hostname>`); individual file operations are not logged
 
-When creating a new shared storage service, you can directly select which runtime services it should be connected to. See [Create Shared Storage](/shared-storage/how-to/create) for details about the creation process.
+:::note
+The `df` command may show incorrect or misleading information for shared storage mounts. Refer to the Zerops GUI for accurate storage metrics.
+:::
 
-### Connect an existing shared storage
+## Connect in Zerops GUI
+
+When creating a new shared storage service, you can directly select which runtime services it should be connected to. See [Create shared storage](/shared-storage/how-to/create) for the creation process.
 
 For existing storage, go to the shared storage service detail page and select **Shared storage connections**. Toggle ON any runtime services you wish to connect to this storage.
 
 <figure style={{ textAlign: 'center', margin: '1rem 0' }}>
   <img
     src="/img/screenshots/connect_shared_storage_1.png"
-    alt="Connecting shared storage during creation"
+    alt="Connecting shared storage to runtime services"
     width="90%"
     height="auto"
   />
 </figure>
 
-## Disconnect a shared storage in Zerops GUI
+To disconnect storage, toggle OFF the desired runtime service in the same place.
 
-To disconnect storage, access the shared storage service detail page, select **Shared storage connections**, and toggle OFF the desired runtime service.
+:::note
+Connecting and disconnecting a shared storage is applied live; the runtime containers are not restarted.
+:::
 
-{/*
-## Connect using zsc
+## Mount and unmount using zsc
 
-Connect shared storage from the command line with the `zsc connectSharedStorage` command. Specify one or more storage names as parameters:
+You can also mount and unmount a shared storage from within a runtime container using the `zsc` command:
 
 ```sh
-zsc connectSharedStorage sharedstorage0
-zsc connectSharedStorage sharedDisk secondDisk
+# Mount a shared storage
+zsc shared-storage mount <storage-hostname>
+
+# Unmount a shared storage
+zsc shared-storage unmount <storage-hostname>
+
+# Wait until the storage mount is ready
+zsc shared-storage wait <storage-hostname>
 ```
 
-Run this command from within your runtime container via web terminal, SSH, or in your `zerops.yaml` file. For more details, see the [Zerops Setup Control documentation](/references/zsc).*/}
\ No newline at end of file
+Run these commands from your runtime container via web terminal or SSH, or as part of your `zerops.yaml` commands. For more details, see the [zsc reference](/references/zsc#shared-storage).
+
+:::caution
+The shared storage must be mounted (through the GUI connection toggle or via `zsc shared-storage mount`) before your application can access the `/mnt/<storage-hostname>` directory.
+
+Before stopping or deleting a shared storage service, you must first disconnect (unmount) it from all runtime services.
+:::
diff --git a/apps/docs/content/shared-storage/how-to/create.mdx b/apps/docs/content/shared-storage/how-to/create.mdx
index 4ac9a20d..921aafdc 100644
--- a/apps/docs/content/shared-storage/how-to/create.mdx
+++ b/apps/docs/content/shared-storage/how-to/create.mdx
@@ -6,11 +6,9 @@ description: Learn how to create shared storage which you can use with your othe
 import GroupCards from '@site/src/components/GroupCards';
 import Video from '@site/src/components/Video';
 
-Shared Storage provides persistent file storage that can be mounted as a POSIX-compatible filesystem to your runtime services. Built on [SeaweedFS ↗](https://github.com/seaweedfs/seaweedfs), it enables reliable data persistence and sharing across services in your infrastructure.
-
 ## Create Using Zerops GUI
 
-First, set up a project in Zerops GUI and add a runtime service. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Shared Storage service:
+Go to your project dashboard and choose **Add new service** in the left menu in the **Services** block. Then add a new Shared Storage service:
 
 <Video
   src="/vids/services/shared-storage.webm"
@@ -19,12 +17,11 @@ First, set up a project in Zerops GUI and add a runtime service. Then go to the
 
 ### Set a Hostname
 
-Enter a unique service identifier like "storage", "files" etc. Duplicate services with the same name in the same project are forbidden.
-
-#### Hostname Limitations:
+Enter a unique service identifier like "storage", "files" etc.
 
 - Maximum 25 characters
 - Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+- Must be unique within the project
 
 :::note
 The hostname is fixed after the service is created. It can't be changed later.
@@ -32,61 +29,72 @@ The hostname is fixed after the service is created. It can't be changed later.
 
 ### Connect to Services
 
-Select one or more project's runtime services in the Share with Services block:
+Select one or more of the project's runtime services in the **Share with Services** block:
 
 <figure style={{ textAlign: 'center', margin: '1rem 0' }}>
   <img
     src="/img/screenshots/connect_shared_storage.png"
-    alt="image"
+    alt="Selecting runtime services to share the storage with"
     width="100%"
     height="auto"
   />
 </figure>
 
-The new Shared Storage will be connected to the selected runtimes.
-
-:::note
-Runtime services can be connected and disconnected at any time even after the shared storage is created.
-:::
+Runtime services can be [connected and disconnected](/shared-storage/how-to/connect) at any time, even after the shared storage is created.
 
 ### Choose Deployment Mode
 
-Choose between **Highly Available** (recommended for production) or **Single Container** (suitable for development) deployment.
+Choose between **Highly Available** (recommended for production) and **Single Container** (suitable for development). See the [mode comparison](/shared-storage/overview#deployment-modes) and [technical details](/shared-storage/tech-details#deployment-modes).
 
 :::warning
-The Shared Storage deployment mode is fixed after the service is created. It can't be changed later.
-
-See [Technical Details](/shared-storage/tech-details#deployment-modes) for more information about deployment modes.
+The deployment mode is fixed after the service is created. It can't be changed later.
 :::
 
 ### Set Auto Scaling Configuration
 
-Configure vertical auto scaling parameters to control resource allocation and costs.
+Configure vertical auto scaling parameters to control resource allocation and costs:
 
 <figure style={{ textAlign: 'center', margin: '1rem 0' }}>
   <img
     src="/img/screenshots/shared_storage_autoscaling.png"
-    alt="image"
+    alt="Shared storage autoscaling configuration"
     width="100%"
     height="auto"
   />
 </figure>
 
 :::note
-For detailed information about auto scaling capabilities and recommendations, see [Technical Details](/shared-storage/tech-details#auto-scaling-configuration).
+Raising the disk limits does not raise the usable data capacity, which is capped at 60GB. See [Storage Capacity](/shared-storage/tech-details#storage-capacity) and [Auto Scaling Configuration](/shared-storage/tech-details#auto-scaling-configuration).
+:::
+
+## Create Using Import YAML
+
+The deployment mode is part of the service type:
+
+```yaml title="zerops-import.yaml"
+services:
+  - # Shared storage service in highly available mode
+    hostname: teststorage
+    type: shared-storage:ha
+```
+
+Use `shared-storage:single` for the single container mode.
+
+:::note
+You can also pin the underlying engine version directly with `seaweedfs:ha@3` or `seaweedfs:single@3`.
 :::
 
-## Create Using zCLI
+Import the file with the [zCLI](/references/cli):
 
-zCLI is the Zerops command-line tool. To create a new Shared Storage service via the command-line, follow these steps:
+```sh
+zcli project service-import zerops-import.yaml
+```
 
-1. [Install & setup zCLI](/references/cli)
-2. Create a project description file
-3. Create a project with a runtime and a Shared Storage service
+To mount the storage into a runtime service in the same import, add the `mount:` parameter to the runtime service. See the [import reference](/references/import#service-mount-shared-storage) for details and requirements.
 
-### Choose Your Runtime
+### Runtime-Specific Guides
 
-<GroupCards heading="Read about how to create a project description file and create a runtime service with a Shared storage." items={languages} />
+<GroupCards heading="Create a runtime service with a Shared storage via import YAML." items={languages} />
 
 export const languages = [
     { name: "Node.js", link: "/nodejs/how-to/shared-storage#create-nodejs-service-with-a-shared-storage-using-zcli" },
@@ -95,4 +103,4 @@ export const languages = [
     { name: "Go", link: "/go/how-to/shared-storage#create-go-service-with-a-shared-storage-using-zcli" },
     { name: ".NET", link: "/dotnet/how-to/shared-storage#create-dotnet-service-with-a-shared-storage-using-zcli" },
     { name: "Rust", link: "/rust/how-to/shared-storage#create-rust-service-with-a-shared-storage-using-zcli" }
-]
\ No newline at end of file
+]
diff --git a/apps/docs/content/shared-storage/how-to/manage.mdx b/apps/docs/content/shared-storage/how-to/manage.mdx
index 1866ce34..c160ae3b 100644
--- a/apps/docs/content/shared-storage/how-to/manage.mdx
+++ b/apps/docs/content/shared-storage/how-to/manage.mdx
@@ -1,26 +1,28 @@
 ---
-title: Manage and Access Shared Storage
-description: Learn how to manage, monitor, and troubleshoot your Shared Storage in Zerops.
+title: Manage and back up Shared Storage
+description: Learn how to manage, monitor, back up, and restore your Shared Storage in Zerops.
 ---
 
-Zerops Shared Storage provides several web interfaces to manage, monitor, and troubleshoot your storage. These interfaces are accessible through the [Zerops VPN](/references/networking/vpn) and offer different capabilities for managing your data and monitoring system performance.
+Zerops Shared Storage provides several web interfaces to manage, monitor, and troubleshoot your storage, and automated encrypted backups of your data.
 
-## Access Web Interfaces
+## Web interfaces
+
+The web interfaces are accessible through the [Zerops VPN](/references/networking/vpn).
 
 ### Filer UI
 
 * `http://<storage-service-hostname>.zerops:8888`
 
-The Filer UI provides a web-based interface for managing files and directories in your Shared Storage:
+A web-based interface for managing files and directories:
 - Browse the directory structure and create new directories
-- Upload new files (up to 64MB) and download existing files
+- Upload new files (up to 64MB per file) and download existing files
 - Rename and delete files and directories
 
 ### Master UI
-* `http://node-stable-1.db.<storage-service-hostname>.zerops:9333`
 
-The Master UI provides system status and monitoring information:
+* `http://node-stable-1.db.<storage-service-hostname>.zerops:9333`
 
+System status and monitoring information:
 - View cluster topology
 - Monitor volume servers
 - Check system status and health
@@ -30,8 +32,7 @@ The Master UI provides system status and monitoring information:
 
 * `http://node-stable-<node-number>.db.<storage-service-hostname>.zerops:8080/ui/index.html`
 
-The Volume UI allows you to monitor individual storage volumes:
-
+Monitoring of individual storage volumes:
 - View volume status
 - Check disk usage
 - Monitor I/O operations
@@ -41,11 +42,42 @@ The Volume UI allows you to monitor individual storage volumes:
 
 Several options are available to help you monitor your Shared Storage:
 
-### Runtime Service Logs
-* Navigate to your runtime service detail page → **Runtime Logs** section → filter using the tag `zerops-mount-<service-hostname>`
+- **Runtime service logs**: navigate to your runtime service detail page, open the **Runtime Logs** section, and filter using the tag `zerops-mount-<service-hostname>` (standard output and error of the mount process)
+- **Shared Storage logs**: access from the Shared Storage service detail page, **Runtime Logs** tab
+- **System and volume status**: monitor replication status, disk usage, and performance metrics through the Master UI and Volume UI
+
+## Backups
+
+Zerops provides automated data backup for Shared Storage services with full encryption.
+
+For general backup information including configuration, scheduling, retention, tagging, quotas, and CLI tools, see the [Zerops Backups](/features/backup) documentation.
+
+### Backup format
+
+Shared Storage backups are created using tar archival:
+
+- **Format**: `.tar.gz` (archive of the directory contents)
+- **Content**: the entire shared volume (`/mnt/<storage-hostname>`)
+- **Storage**: encrypted and stored in isolated object storage
+
+### Restoring backups
+
+To restore a Shared Storage backup:
+
+1. Download the backup file (`.tar.gz`) from the Zerops UI.
+2. Transfer the archive into a runtime service that has the shared storage [connected](/shared-storage/how-to/connect), for example over the [Zerops VPN](/references/networking/vpn).
+3. Extract the archive into the mount directory from within the runtime container:
+
+```sh
+tar -xzf backup.tar.gz -C /mnt/<storage-hostname>
+```
+
+:::note
+Do not restore by uploading files through the Filer UI. Uploads there are limited to 64MB per file, so extracting the archive directly into the mounted directory is the reliable path.
+:::
 
-### Shared Storage Logs
-* Access from the Shared Storage service detail page → **Runtime Logs** tab → browse or search for relevant information
+### Best practices
 
-### System and Volume Status
-* Monitor replication status, disk usage, and performance metrics through the Master UI and Volume UI
+- Regularly clean up unnecessary files from your Shared Storage to reduce backup size
+- Create manual backups with protected tags before major file operations or migrations
+- Test your restore process periodically to ensure data integrity
diff --git a/apps/docs/content/shared-storage/how-to/use.mdx b/apps/docs/content/shared-storage/how-to/use.mdx
deleted file mode 100644
index cacf65cc..00000000
--- a/apps/docs/content/shared-storage/how-to/use.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Usage & Limitations of Shared Storage
-description: Learn how to use Shared Storage in Zerops and understand its use cases and limitations.
----
-
-Once a Shared Storage is [connected](/shared-storage/how-to/connect) to a runtime service, Zerops will create a new folder `/mnt/[shared storage name]` in the runtime service's filesystem.
-
-For example, `/mnt/teststorage` for a `teststorage` Shared Storage:
-
-<figure style={{ textAlign: 'center', margin: '1rem 0' }}>
-  <img
-    src="/img/screenshots/connect_shared_storage_2.png"
-    alt="image"
-    width="100%"
-    height="auto"
-  />
-</figure>
-
-:::note
-The content of this folder is shared among all containers of the connected runtime service.
-
-If you connect multiple runtimes, the content of the folder will be shared among all containers of these services.
-:::
-
-## Mount Points and Multiple Volumes
-
-- Multiple storage volumes can be mounted to a single service (e.g., `/mnt/files1`, `/mnt/files2`, etc.)
-- Shared storage mount is only available in runtime containers, not during build and prepare runtime phases
-- All filesystem operations are automatically logged to runtime logs
-
-For technical details about mount behavior and filesystem capabilities, see the [Technical Details](/shared-storage/tech-details#mount-integration) page.
-
-## Use Cases
-
-Shared Storage is ideal for:
-
-- **Persistent filesystem-based databases**: SQLite, Prometheus DB, etc.
-- **Configuration sharing**: Deploy configurations once and share across multiple services
-  - Example: Deploy Apache Airflow configurations and DAG files once and share with all worker nodes
-- **Alternative to object storage**: For applications that require filesystem semantics rather than object storage
-- **Application data**: Store and serve images, documents, and other assets
-
-## Performance Considerations
-
-When using Shared Storage, keep in mind:
-
-- For write-heavy workloads, consider batching operations
-- Minimize operations with many small files for better performance
-
-For more detailed information about performance constraints and limitations, see the [Technical Details](/shared-storage/tech-details#performance-considerations) page.
-
-## Troubleshooting
-
-### Common Issues
-
-- The `df` command may show incorrect or misleading information when used with shared storage mounts. Please refer to the Zerops GUI for accurate storage metrics.
\ No newline at end of file
diff --git a/apps/docs/content/shared-storage/overview.mdx b/apps/docs/content/shared-storage/overview.mdx
index f1cbb1fe..f12cfdde 100644
--- a/apps/docs/content/shared-storage/overview.mdx
+++ b/apps/docs/content/shared-storage/overview.mdx
@@ -1,98 +1,153 @@
 ---
-title: Shared Storage Overview
-description: Learn about working with Shared Storage with ease in Zerops.
+title: Shared Storage on Zerops
+description: Managed shared disk storage on Zerops. A POSIX-compatible filesystem mounted into your runtime containers, with optional high availability and automated backups.
 ---
 
 import DocCardList from '@theme/DocCardList';
 import Icons from '@theme/Icon';
-import LargeCardList from '@site/src/components/LargeCardList';
-import LargeCard from '@site/src/components/LargeCard';
 
-# Shared Storage
+Zerops **Shared Storage** is a managed disk volume that mounts as a POSIX-compatible filesystem into your runtime services. Files written by one container are immediately visible to every other container that mounts the same storage, whether they belong to the same service or to different services in the project.
 
-Zerops provides a fully managed and scaled **Shared Storage** service, which can be mounted to your runtime services. It offers:
-- Persistent file sharing between containers of the same service or different services
-- Standard filesystem operations through a POSIX-compatible interface
-- Built-in high-availability configuration
+Under the hood it runs [SeaweedFS ↗](https://github.com/seaweedfs/seaweedfs), a distributed filesystem optimized for high-volume storage. See [Technical details](/shared-storage/tech-details) for the architecture.
 
-## Documentation Sections
+## Quick start
+
+Add a shared storage to your project and mount it into a runtime service with a `zerops-import.yaml`:
+
+```yaml title="zerops-import.yaml"
+services:
+  - hostname: teststorage
+    # type is shared-storage:{mode}
+    type: shared-storage:ha
+
+  - hostname: app
+    type: nodejs@22
+    buildFromGit: https://github.com/myorg/myapp
+    # mount the storage into /mnt/teststorage
+    mount:
+      - teststorage
+```
+
+The storage appears in the runtime containers at `/mnt/teststorage`. See [Create shared storage](/shared-storage/how-to/create) for the GUI flow and configuration details, and [Connect & mount](/shared-storage/how-to/connect) for how the mount behaves.
+
+## Use cases
+
+Shared Storage is a good fit for:
+
+- **Configuration sharing**: deploy configuration once and share it across services (e.g. Apache Airflow configuration and DAG files shared with all worker nodes)
+- **Application data**: user uploads, images, documents, and other assets shared between containers (avoid huge trees of tiny files, see [performance considerations](/shared-storage/tech-details#performance-considerations))
+- **Fallback to object storage**: applications that strictly require filesystem semantics and cannot work with [object storage](/object-storage/overview)
+
+:::caution Not suitable for databases
+Do **not** run databases on Shared Storage. This includes SQLite, Prometheus TSDB, and other filesystem-based databases.
+
+- File locks are enforced **per mount only**: a lock held in one container does not prevent another container from writing to the same file, which leads to data corruption.
+- The underlying storage engine is an append-only chunk store: every modification writes new chunks, so the frequent small writes typical for databases cause heavy write amplification.
+
+Use [managed databases](/postgresql/overview) instead. For storing database *backups*, prefer [object storage](/object-storage/overview): it is cheaper and better suited for write-once files.
+:::
+
+## Deployment modes
+
+Choose the reliability model when you create the service. It is set through the service `type` and is **fixed for the life of the service**.
+
+<table className="w-full my-1.5">
+  <thead>
+    <tr>
+      <th className="w-fit" style={{ minWidth: '75px' }}>Mode</th>
+      <th className="w-fit" style={{ minWidth: '200px' }}>type</th>
+      <th className="w-fit">What it is</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td className="w-fit"><b>Highly Available</b></td>
+      <td className="w-fit"><code>shared-storage:ha</code></td>
+      <td className="w-fit">Two containers with data and metadata replicated 1:1 across both, with automatic repair when a node fails. Recommended for production.</td>
+    </tr>
+    <tr>
+      <td className="w-fit"><b>Single container</b></td>
+      <td className="w-fit"><code>shared-storage:single</code></td>
+      <td className="w-fit">One container, so lower cost but no redundancy. All data is lost if the container fails. Good for development and non-critical data.</td>
+    </tr>
+  </tbody>
+</table>
+
+## Key limits
+
+- The storage holds at most **60GB of data**, regardless of the disk resource in autoscaling. See [storage capacity](/shared-storage/tech-details#storage-capacity).
+- File locks work **only within a single container's mount**, not across containers. See [filesystem capabilities](/shared-storage/tech-details#filesystem-capabilities).
+- The mount is available only in runtime containers, not during build and prepare phases.
+
+## Next steps
 
 <DocCardList
-  colSize={4}
+  colSize={6}
   items={[
     {
       type: 'link',
-      href: '/shared-storage/how-to/connect',
-      label: 'Connect to Services',
+      href: '/shared-storage/how-to/create',
+      label: 'Create shared storage',
       customProps: {
-        icon: Icons['link'],
-        description: 'Connect your Shared Storage to runtime services.',
+        icon: Icons['computer-desktop'],
+        description: 'Create a service in the GUI or with zerops-import.yaml.',
       },
     },
     {
       type: 'link',
-      href: '/shared-storage/how-to/use',
-      label: 'Usage & Limitations',
+      href: '/shared-storage/how-to/connect',
+      label: 'Connect & mount',
       customProps: {
-        icon: Icons['chart-bar'],
-        description: 'Learn how to save and access data, along with use cases and technical limits.',
+        icon: Icons['link'],
+        description: 'Connect runtime services and understand how the mount behaves.',
       },
     },
     {
       type: 'link',
       href: '/shared-storage/how-to/manage',
-      label: 'Management & Access',
+      label: 'Manage & backups',
       customProps: {
         icon: Icons['tools'],
-        description: 'Access UI components and troubleshoot common issues.',
-      },
-    },
-    {
-      type: 'link',
-      href: '/shared-storage/how-to/backup',
-      label: 'Backups',
-      customProps: {
-        icon: Icons['archive-box'],
-        description: 'Configure automatic backups of your data.',
+        description: 'Web interfaces, monitoring, backups, and restore.',
       },
     },
     {
       type: 'link',
       href: '/shared-storage/tech-details',
-      label: 'Technical Details',
+      label: 'Technical details',
       customProps: {
         icon: Icons['document-text'],
-        description: 'Explore the technical architecture and deployment options.',
+        description: 'Architecture, storage engine behavior, limits, and autoscaling.',
       },
     },
   ]}
 />
 
-*Need help? Join our [Discord community](https://discord.gg/zeropsio).*
+## Need help?
 
-## Popular Guides
+Stuck, or want to share what you built? Our core team and community are on Discord.
 
 <DocCardList
   colSize={6}
   items={[
     {
       type: 'link',
-      href: '/references/cli',
-      label: 'zCLI',
+      href: 'https://discord.com/invite/WDvCZ54',
+      label: 'Discord',
       customProps: {
-        icon: Icons['command-line'],
+        icon: Icons['discord'],
         description:
-          'Get even more out of Zerops with the zCLI command line tool.',
+          'Join the Zerops community on Discord. Ask questions and share your tips.',
       },
     },
     {
       type: 'link',
-      href: '/references/networking/vpn',
-      label: 'Zerops VPN',
+      href: '/references/cli',
+      label: 'zCLI',
       customProps: {
-        icon: Icons['globe-europe'],
-        description: 'Connect to your services easily with Zerops VPN.',
+        icon: Icons['command-line'],
+        description: 'Get more out of Zerops with the command-line tool.',
       },
     },
   ]}
-/>
\ No newline at end of file
+/>
diff --git a/apps/docs/content/shared-storage/tech-details.mdx b/apps/docs/content/shared-storage/tech-details.mdx
index 0b4b07d4..0736a470 100644
--- a/apps/docs/content/shared-storage/tech-details.mdx
+++ b/apps/docs/content/shared-storage/tech-details.mdx
@@ -1,29 +1,25 @@
 ---
 title: Shared Storage Technical Details
-description: Explore the technical architecture and deployment options of Zerops Shared Storage.
+description: Explore the technical architecture, storage engine behavior, limits, and autoscaling of Zerops Shared Storage.
 ---
 
 import ResourceTable from '/src/components/ResourceTable';
 
-Zerops Shared Storage is built on [SeaweedFS](https://github.com/seaweedfs/seaweedfs), a distributed filesystem optimized for high-volume storage with efficient retrieval.
+Zerops Shared Storage is built on [SeaweedFS ↗](https://github.com/seaweedfs/seaweedfs), a distributed filesystem optimized for high-volume storage with efficient retrieval.
 
 ## Architecture
 
 Shared Storage consists of three main components:
-- **Master Server**: Manages metadata and coordinates volume servers
-- **Volume Servers**: Store the actual file data
-- **Filer**: Provides a POSIX-compatible interface for file operations
 
-An **automatic vacuum process** helps maintain optimal storage performance by reclaiming space from deleted files. This process is triggered when the size of deleted content exceeds 15% (reduced from the default 30%).
+- **Master Server**: manages metadata and coordinates volume servers
+- **Volume Servers**: store the actual file data
+- **Filer**: provides a POSIX-compatible interface for file operations
 
-### Mount Integration
+### Storage Engine Behavior
 
-When connected to a runtime service:
-- Storage is mounted at `/mnt/<storage-hostname>`
-- Mount point is owned by the `zerops` user and group (no sudo required)
-- All filesystem operations are logged to runtime logs (tagged as `zerops-mount-<service-hostname>`)
-- Mounting will overwrite any existing content in the mount directory
-- Shared storage mount is only available in runtime containers, not during build and prepare runtime phases
+SeaweedFS stores file data in append-only volumes. Files are split into chunks, and when a file is modified, new chunks are written while the old ones remain on disk until they are reclaimed. Frequent small modifications of existing files therefore cause significant write amplification, which is one of the reasons Shared Storage is [not suitable for databases](/shared-storage/overview#use-cases).
+
+An **automatic vacuum process** reclaims the space occupied by deleted and superseded chunks. This process is triggered when the size of deleted content exceeds 15% (reduced from the SeaweedFS default of 30%).
 
 ## Deployment Modes
 
@@ -33,8 +29,8 @@ Zerops provides Shared Storage in two deployment modes:
 
 Recommended for production environments where data reliability is critical.
 
-- **Architecture**: 2 volume servers with the master located on one of them
-- **Data Durability**: Data and filer metadata are replicated 1:1 across nodes
+- **Architecture**: Two containers, each running its own filer and volume server; the master server runs on the first container
+- **Data Durability**: Data and filer metadata are replicated 1:1 across both containers
 - **Fault Tolerance**:
     - If a node fails, an automatic repair process begins
     - A new container replaces the failed one
@@ -47,7 +43,6 @@ Suitable for development environments or non-critical data storage.
 
 - **Architecture**: Master, volume, and filer server all located on a single container
 - **Data Durability**: All data is lost if the container fails
-- **Recommended For**: Development environments or temporary data storage
 
 :::warning
 The deployment mode is fixed after the service is created and cannot be changed later.
@@ -59,35 +54,38 @@ Shared Storage supports standard POSIX filesystem operations:
 
 - Create, read, update, and delete files and directories
 - Set permissions (with some limitations)
-- Standard file locking operations
+- File locking (per mount only, see the warning below)
 - Hard and symbolic links
 - Directory listing and traversal
 
-For a complete list of supported features, see the [SeaweedFS FUSE documentation](https://github.com/seaweedfs/seaweedfs/wiki/FUSE-Mount#supported-features).
+For a complete list of supported features, see the [SeaweedFS FUSE documentation ↗](https://github.com/seaweedfs/seaweedfs/wiki/FUSE-Mount#supported-features).
 
-## Resource Constraints
+:::caution File locks are per-mount only
+File locks (`flock`, POSIX locks) are enforced only within a single container's mount. A process in another container can freely write to a file you hold locked. Do not rely on file locking for coordination between containers, and do not run [lock-dependent workloads such as databases](/shared-storage/overview#use-cases) on Shared Storage.
+:::
 
-### Storage Limits
+## Storage Capacity
 
-- Maximum storage space: 60GB (can be increased via support request)
-- Maximum file size: Unlimited within the 60GB total storage constraint
-- Maximum upload size via Filer UI: 64MB
+:::caution The 60GB data limit is independent of disk scaling
+A Shared Storage service holds at most **60GB of data**, no matter how much disk the service scales to. The disk resource (up to 250GB) provides headroom for the vacuum process and filesystem metadata; raising the disk limits in autoscaling does **not** increase the amount of data you can store.
 
-### Memory Usage
+If you need more than 60GB, contact support.
+:::
 
-- Base memory consumption: ~60MB when idle
-- Peak memory usage: ~150MB under higher filesystem loads
-- Optimized for low RAM usage (may trade off some performance)
+- Maximum storage space: 60GB (can be increased via support request)
+- Maximum file size: no fixed limit through the mount (files are stored in chunks), up to the available storage space
+- Maximum upload size via Filer UI: 64MB per file
 
-### Performance Considerations
+## Performance Considerations
 
-- **Latency**: Higher latency compared to local storage due to network-based distributed architecture
-- **Write Performance**: For write-heavy workloads, consider batching operations
-- **Small Files**: Minimize operations with many small files for better performance
+- **Latency**: higher latency compared to local storage due to the network-based distributed architecture
+- **Write performance**: for write-heavy workloads, batch operations where possible
+- **Small files**: minimize operations with many small files for better performance
+- **Mount process memory**: the mount process runs inside each connected runtime container and consumes its memory, roughly 60MB when idle and around 150MB under higher filesystem loads; it is optimized for low RAM usage, which may trade off some performance
 
 ## Auto Scaling Configuration
 
-Zerops scales Shared Storage services automatically by raising or lowering the hardware resources of each database container.
+Zerops scales Shared Storage services automatically by raising or lowering the hardware resources of each container.
 
 Vertical auto scaling has the following default configuration:
 
@@ -100,10 +98,12 @@ Vertical auto scaling has the following default configuration:
       }
 }} />
 
+:::note
+Disk size only gives the storage engine working space; the usable data capacity stays capped at 60GB. See [Storage Capacity](#storage-capacity).
+:::
+
 For most cases, the default parameters will work without issues. If you need to limit the cost of the Shared Storage service, lower the maximal resources. Zerops will never scale above the selected maximums.
 
-When you are experiencing problems with insufficient Shared Storage performance or capacity, increase the minimal resources. Zerops will never scale below the selected minimums.
+When you are experiencing problems with insufficient Shared Storage performance, increase the minimal resources. Zerops will never scale below the selected minimums.
 
-:::note
-You can change the auto scaling parameters later.
-:::
\ No newline at end of file
+You can change the auto scaling parameters at any time.
diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js
index ef11b68e..85d904d0 100644
--- a/apps/docs/sidebars.js
+++ b/apps/docs/sidebars.js
@@ -2763,22 +2763,12 @@ module.exports = {
         {
           type: 'doc',
           id: 'shared-storage/how-to/connect',
-          label: 'Connect shared storage',
-        },
-        {
-          type: 'doc',
-          id: 'shared-storage/how-to/use',
-          label: 'Usage & Limitations',
+          label: 'Connect & mount',
         },
         {
           type: 'doc',
           id: 'shared-storage/how-to/manage',
-          label: 'Manage & Access shared storage',
-        },
-        {
-          type: 'doc',
-          id: 'shared-storage/how-to/backup',
-          label: 'Backup shared storage',
+          label: 'Manage & backups',
         },
       ],
     },
diff --git a/apps/docs/src/components/content/shared-storage.mdx b/apps/docs/src/components/content/shared-storage.mdx
index 2bc3865c..2b2062c1 100644
--- a/apps/docs/src/components/content/shared-storage.mdx
+++ b/apps/docs/src/components/content/shared-storage.mdx
@@ -13,8 +13,7 @@ project:
 services:
   - # Shared storage service
     hostname: teststorage
-    type: shared-storage
-    mode: NON_HA
+    type: shared-storage:single
 
   - # {{serviceDisplay}} service
     hostname: app
diff --git a/apps/docs/static/data.json b/apps/docs/static/data.json
index fc9ba4a5..9dfbb987 100644
--- a/apps/docs/static/data.json
+++ b/apps/docs/static/data.json
@@ -321,11 +321,11 @@
     "readable": ["25.3"]
   },
   "seaweedfs": {
-    "import": [["seaweedfs@3"]],
+    "import": [["seaweedfs:single@3", "seaweedfs:ha@3"]],
     "readable": ["3"]
   },
   "sharedstorage": {
-    "import": [["shared-storage"]]
+    "import": [["shared-storage:single", "shared-storage:ha"]]
   },
   "objectstorage": {
     "import": [["object-storage"]]