diff --git a/Directory.Build.props b/Directory.Build.props
index 78e9842..0d3c4ce 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -11,9 +11,16 @@
     <PackageProjectUrl>https://github.com/chrison-dev/SynoSharp</PackageProjectUrl>
     <RepositoryType>git</RepositoryType>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <!-- Embed the repo README in every package so nuget.org renders it. -->
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <!-- Embed symbols in the assembly (GitHub Packages doesn't take .snupkg). -->
     <DebugType>embedded</DebugType>
   </PropertyGroup>
 
+  <!-- Pack the repo-root README into every packable project. -->
+  <ItemGroup Condition="Exists('$(MSBuildThisFileDirectory)README.md')">
+    <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="\" Visible="false" />
+  </ItemGroup>
+
 </Project>
diff --git a/README.md b/README.md
index c295925..fda63ad 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,31 @@
 # SynoSharp
 
+[![NuGet](https://img.shields.io/nuget/v/Chrison.SynoSharp.svg)](https://www.nuget.org/packages/Chrison.SynoSharp/)
+[![Downloads](https://img.shields.io/nuget/dt/Chrison.SynoSharp.svg)](https://www.nuget.org/packages/Chrison.SynoSharp/)
+[![ci](https://github.com/Chrison-dev/SynoSharp/actions/workflows/ci.yml/badge.svg)](https://github.com/Chrison-dev/SynoSharp/actions/workflows/ci.yml)
+[![Built with Fallout](https://img.shields.io/badge/built%20with-Fallout-8A2BE2)](https://github.com/Fallout-build/Fallout)
+[![License: MIT](https://img.shields.io/github/license/Chrison-dev/SynoSharp.svg)](LICENSE)
+
 A C# client for **Synology DSM** IaC. Sibling to ProxmoxSharp/UnifiSharp — but
 **not code-generated**: Synology publishes no settings/deploy API schema, so per
-[ADR-0002](https://github.com/chrison-dev/Homelab/blob/main/docs/adr/ADR-0002-synosharp.md)
+[ADR-0002](https://github.com/Chrison-Homelab/Homelab/blob/main/docs/adr/ADR-0002-synosharp.md)
 this is a hand-written **read-API client** (now) + an **SSH-runner** for mutations (later).
 
+```sh
+dotnet add package Chrison.SynoSharp
+```
+
+```mermaid
+flowchart LR
+  APP["🧩 homelab engine / CLI"] -->|"read / discover"| WEB["🌐 DSM Web API<br/>SYNO.API.Auth → entry.cgi → SYNO.Core.*"]
+  APP -. "mutations (write phase)" .-> SSH["🔐 SSH-runner<br/>syno* CLI + synowebapi"]
+  WEB --> SNAP["📊 SynologySnapshot"]
+  SSH --> NAS["🗄️ DSM 7.1 · DS1813+"]
+  WEB --- NAS
+  classDef future fill:#f3f4f6,stroke:#9ca3af,color:#6b7280;
+  class SSH future;
+```
+
 ## Approach
 
 - **Read / discover** → the DSM **Web API** (`SYNO.API.Auth` → `entry.cgi` →
diff --git a/src/SynoSharp/SynoSharp.csproj b/src/SynoSharp/SynoSharp.csproj
index bbbaed0..9ef269a 100644
--- a/src/SynoSharp/SynoSharp.csproj
+++ b/src/SynoSharp/SynoSharp.csproj
@@ -6,7 +6,7 @@
     <Nullable>enable</Nullable>
     <!-- Independent SemVer. No generated .Api project — Synology has no published
          schema (ADR-0002), so this is a hand-written client. -->
-    <VersionPrefix>0.1.0</VersionPrefix>
+    <VersionPrefix>0.1.1</VersionPrefix>
     <!-- Public nuget.org ID uses the reserved Chrison.* prefix (consistent with the
          sibling clients). AssemblyName/RootNamespace stay 'SynoSharp' (project name)
          so consumer code — `using SynoSharp;` — is unchanged. -->