diff --git a/README.md b/README.md
index 91d167a1..aee5006b 100644
--- a/README.md
+++ b/README.md
@@ -32,9 +32,7 @@
 <br />
 <br />
 
-<details>
-<summary><sub>Other install methods</sub></summary>
-<br />
+**Package-manager alternatives**
 
 <sub>pnpm</sub><br />
 <pre><code>pnpm dlx runpane@latest</code></pre>
@@ -46,12 +44,16 @@
 <pre><code>npm i -g runpane
 runpane setup</code></pre>
 
+**Shell installers**
+
 <sub>Mac / Linux shell installer</sub><br />
 <pre><code>curl -fsSL https://runpane.com/install.sh | sh</code></pre>
 
 <sub>Windows PowerShell installer</sub><br />
 <pre><code>irm https://runpane.com/install.ps1 | iex</code></pre>
 
+**Direct downloads**
+
 <a href="https://runpane.com/api/download?platform=mac&source=readme">
   <img src="https://img.shields.io/badge/Download_for_macOS-000?style=for-the-badge&logo=apple&logoColor=white" height="40" alt="Download for macOS">
 </a>
@@ -62,8 +64,6 @@ runpane setup</code></pre>
   <img src="https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" height="40" alt="Download for Linux">
 </a>
 
-</details>
-
 <br />
 <br />
 
@@ -204,7 +204,7 @@ npx --yes runpane@latest
 The wizard can install Pane on this machine, configure this machine as a remote
 host, update Pane, or run diagnostics.
 
-### Advanced Install Methods
+### Package Manager Commands
 
 Explicit desktop install:
 
@@ -221,6 +221,8 @@ npm i -g runpane
 runpane setup
 ```
 
+### Shell Installers
+
 Mac / Linux shell installer:
 
 ```bash
diff --git a/packages/runpane-py/README.md b/packages/runpane-py/README.md
index 94550b78..c1c2e695 100644
--- a/packages/runpane-py/README.md
+++ b/packages/runpane-py/README.md
@@ -95,6 +95,22 @@ PyPI package downloads use `source=pip` when requesting release artifacts from
 `runpane.com/api/download`. If that route is unavailable, the CLI falls back to
 matching GitHub release assets and prints a warning.
 
+## Maintenance Notes
+
+Keep the npm and PyPI clients in sync with each Pane release. When changing
+shared installer behavior:
+
+- If release asset names or platforms change, update both npm and PyPI wrapper
+  artifact matching.
+- If `runpane` CLI behavior changes, update both clients and the shared smoke
+  tests.
+- If the website `/api/download` contract changes, verify npm and PyPI fallback
+  behavior.
+- If daemon setup flags change, update docs, README files, and wrapper tests
+  together.
+- Keep the CI wrapper matrix green: Linux, macOS, Windows, Node 18/22, and
+  Python 3.8/3.13.
+
 ## Publishing
 
 This package should be published through PyPI Trusted Publishing from GitHub
diff --git a/packages/runpane/README.md b/packages/runpane/README.md
index 6bba43d2..12991073 100644
--- a/packages/runpane/README.md
+++ b/packages/runpane/README.md
@@ -97,6 +97,22 @@ npm package downloads use `source=npm` when requesting release artifacts from
 `runpane.com/api/download`. If that route is unavailable, the CLI falls back to
 matching GitHub release assets and prints a warning.
 
+## Maintenance Notes
+
+Keep the npm and PyPI clients in sync with each Pane release. When changing
+shared installer behavior:
+
+- If release asset names or platforms change, update both npm and PyPI wrapper
+  artifact matching.
+- If `runpane` CLI behavior changes, update both clients and the shared smoke
+  tests.
+- If the website `/api/download` contract changes, verify npm and PyPI fallback
+  behavior.
+- If daemon setup flags change, update docs, README files, and wrapper tests
+  together.
+- Keep the CI wrapper matrix green: Linux, macOS, Windows, Node 18/22, and
+  Python 3.8/3.13.
+
 ## Publishing
 
 This package should be published through npm Trusted Publishing from GitHub