fix: stabilize plugin config directories

2 files changed, 15 insertions, 3 deletions

diff --git a/docs/next/CHANGELOG.md b/docs/next/CHANGELOG.md
index d30ef572..57251781 100644
--- a/docs/next/CHANGELOG.md
+++ b/docs/next/CHANGELOG.md
@@ -9,6 +9,9 @@
 - Added `herdr plugin install <owner>/<repo>[/subdir...]`, `plugin uninstall`,
   source metadata in `plugin.list`, offline registry fallback, and a
   human-readable default `plugin list` with `--json` for scripts.
+- Added `herdr plugin config-dir <id>` and automatic plugin config/state
+  directory creation so plugin setup docs can point users at a stable config
+  path.
 - Added supporting plugin host APIs for `pane.current`, `pane.process_info`,
   `client.window_title.set/clear`, `layout.export/apply`, plugin pane placement,
   plugin invocation context/env injection, and plugin pane ownership across
@@ -17,6 +20,9 @@
 
 ### Changed
 - Bumped the client/server protocol version to 14 for `pane.move` compatibility. (#299)
+- Plugin runtime config directories now use stable, readable plugin-id paths
+  instead of checkout hashes; existing legacy config directories are copied into
+  the new location when first seen.
 - Public workspace, tab, and pane ids are now short stable handles such as `w1`, `w1:t1`, and `w1:p1`; closed tab and pane ids no longer retarget later resources. (#569)
 
 ### Fixed
diff --git a/docs/next/website/src/content/docs/plugins.mdx b/docs/next/website/src/content/docs/plugins.mdx
index 0b548b64..cf5b4ff2 100644
--- a/docs/next/website/src/content/docs/plugins.mdx
+++ b/docs/next/website/src/content/docs/plugins.mdx
@@ -143,6 +143,7 @@ Install an example plugin:
 
 ```bash
 herdr plugin install ogulcancelik/herdr-plugin-examples/agent-telegram-notify
+herdr plugin config-dir examples.agent-telegram-notify
 herdr plugin list
 herdr plugin action list --plugin examples.agent-telegram-notify
 ```
@@ -151,6 +152,7 @@ When you are authoring a local plugin, link the working directory instead:
 
 ```bash
 herdr plugin link /path/to/plugin
+herdr plugin config-dir example.layout
 herdr plugin action list --plugin example.layout
 herdr plugin action invoke example.layout.apply
 herdr plugin pane open --plugin example.layout --entrypoint board
@@ -163,7 +165,9 @@ terminals, runs supported build commands, then stores the checkout under
 Herdr-managed plugin data and registers it. Use `--yes` for noninteractive
 installs. Reinstalling a GitHub-managed plugin replaces that managed checkout.
 Installing over a locally linked plugin is refused; unlink or uninstall the
-local plugin first.
+local plugin first. `plugin install` and `plugin link` create the plugin's
+config and state directories, and `plugin config-dir <id>` prints the config
+directory for setup docs and shell scripts.
 
 `plugin uninstall <id-or-source>` unregisters the plugin. For GitHub-managed
 installs it also removes the managed checkout, and it accepts either the plugin
@@ -206,8 +210,10 @@ receive `HERDR_PLUGIN_ACTION_ID`; event hooks receive `HERDR_PLUGIN_EVENT` and
 user credentials or durable state there, because GitHub-installed plugin roots
 are managed source checkouts. Put user-editable config such as `.env` files
 under `HERDR_PLUGIN_CONFIG_DIR`, and put local runtime state under
-`HERDR_PLUGIN_STATE_DIR`. Herdr does not read, create, migrate, validate, sync,
-or delete their contents. The plugin owns the file format and lifecycle.
+`HERDR_PLUGIN_STATE_DIR`. Herdr creates those directories and seeds
+`HERDR_PLUGIN_CONFIG_DIR` from the legacy plugin config locations when present,
+but it does not validate, sync, or delete their contents. The plugin owns the
+file format and lifecycle.
 
 `HERDR_PLUGIN_CONTEXT_JSON` can include workspace, tab, focused pane, worktree,
 agent, selected text, clicked URL, and link handler fields when they are