diff --git a/CLAUDE.md b/CLAUDE.md
index 61b77500..e5930fdd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,8 +4,14 @@
 - `src/plugin_system/` — Plugin loader, manager, store manager, base plugin class
 - `web_interface/` — Flask web UI (blueprints, templates, static JS)
 - `config/config.json` — User plugin configuration (persists across plugin reinstalls)
-- `plugins/` — Installed plugins directory (gitignored)
-- `plugin-repos/` — Development symlinks to monorepo plugin dirs
+- `plugin-repos/` — **Default** plugin install directory used by the
+  Plugin Store, set by `plugin_system.plugins_directory` in
+  `config.json` (default per `config/config.template.json:130`).
+  Not gitignored.
+- `plugins/` — Legacy/dev plugin location. Gitignored (`plugins/*`).
+  Used by `scripts/dev/dev_plugin_setup.sh` for symlinks. The plugin
+  loader falls back to it when something isn't found in `plugin-repos/`
+  (`src/plugin_system/schema_manager.py:77`).
 
 ## Plugin System
 - Plugins inherit from `BasePlugin` in `src/plugin_system/base_plugin.py`
diff --git a/docs/PLUGIN_DEVELOPMENT_GUIDE.md b/docs/PLUGIN_DEVELOPMENT_GUIDE.md
index 5315bbe1..e368bd62 100644
--- a/docs/PLUGIN_DEVELOPMENT_GUIDE.md
+++ b/docs/PLUGIN_DEVELOPMENT_GUIDE.md
@@ -12,6 +12,15 @@ When developing plugins in separate repositories, you need a way to:
 
 The solution uses **symbolic links** to connect plugin repositories to the `plugins/` directory, combined with a helper script to manage the linking process.
 
+> **Plugin directory note:** the dev workflow described here puts
+> symlinks in `plugins/`. The plugin loader's *production* default is
+> `plugin-repos/` (set by `plugin_system.plugins_directory` in
+> `config.json`), but it falls back to `plugins/` so the dev symlinks
+> are picked up automatically. The Plugin Store installs to
+> `plugin-repos/`. If you want both your dev symlinks *and* store
+> installs to share the same directory, set `plugins_directory` to
+> `plugins` in the General tab of the web UI.
+
 ## Quick Start
 
 ### 1. Link a Plugin from GitHub
diff --git a/src/common/README.md b/src/common/README.md
index f381614e..4f9b0b6b 100644
--- a/src/common/README.md
+++ b/src/common/README.md
@@ -71,6 +71,17 @@ General-purpose utility functions:
 - Boolean parsing
 - Logger creation (deprecated - use `src.logging_config.get_logger()`)
 
+## Permission Utilities (`permission_utils.py`)
+
+Helpers for ensuring directory permissions and ownership are correct
+when running as a service (used by `CacheManager` to set up its
+persistent cache directory).
+
+## CLI Helpers (`cli.py`)
+
+Shared CLI argument parsing helpers used by `scripts/dev/*` and other
+command-line entry points.
+
 ## Best Practices
 
 1. **Use centralized logging**: Import from `src.logging_config` instead of creating loggers directly
diff --git a/systemd/README.md b/systemd/README.md
index 2e638e82..a2408954 100644
--- a/systemd/README.md
+++ b/systemd/README.md
@@ -28,14 +28,29 @@ These service files are installed by the installation scripts in `scripts/instal
 
 ## Manual Installation
 
-If you need to install a service manually:
-
-```bash
-sudo cp systemd/ledmatrix.service /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable ledmatrix.service
-sudo systemctl start ledmatrix.service
-```
+> **Important:** the unit files in this directory contain
+> `__PROJECT_ROOT_DIR__` placeholders that the install scripts replace
+> with the actual project directory at install time. Do **not** copy
+> them directly to `/etc/systemd/system/` — the service will fail to
+> start with `WorkingDirectory=__PROJECT_ROOT_DIR__` errors.
+>
+> Always install via the helper script:
+>
+> ```bash
+> sudo ./scripts/install/install_service.sh
+> ```
+>
+> If you really need to do it by hand, substitute the placeholder
+> first:
+>
+> ```bash
+> PROJECT_ROOT="$(pwd)"
+> sed "s|__PROJECT_ROOT_DIR__|$PROJECT_ROOT|g" systemd/ledmatrix.service \
+>   | sudo tee /etc/systemd/system/ledmatrix.service > /dev/null
+> sudo systemctl daemon-reload
+> sudo systemctl enable ledmatrix.service
+> sudo systemctl start ledmatrix.service
+> ```
 
 ## Service Management