docs: finalize release docs and refresh agent skill

1 files changed, 34 insertions, 5 deletions

diff --git a/website/src/content/docs/plugins.mdx b/website/src/content/docs/plugins.mdx
index 500ae5a3..1d93bedc 100644
--- a/website/src/content/docs/plugins.mdx
+++ b/website/src/content/docs/plugins.mdx
@@ -73,6 +73,9 @@ command = ["npm", "ci"]
 command = ["npm", "run", "build"]
 platforms = ["linux", "macos"]
 
+[[startup]]
+command = ["node", "dist/restore.js"]
+
 [[actions]]
 id = "apply"
 title = "Apply layout"
@@ -109,9 +112,10 @@ dots. Each id type must be unique inside a plugin. Herdr qualifies action ids
 as `plugin.id.action` when it needs a globally unique name.
 
 Use `platforms = ["linux", "macos", "windows"]` to declare where the plugin
-can run. Build commands, actions, event hooks, panes, and link handlers can
-also declare their own `platforms`; item-level platforms override the top-level
-list. Local plugins without top-level `platforms` link with a warning.
+can run. Build commands, startup hooks, actions, event hooks, panes, and link
+handlers can also declare their own `platforms`; item-level platforms override
+the top-level list. Local plugins without top-level `platforms` link with a
+warning.
 
 `command` values are argv arrays. Herdr does not run them through a shell, so
 there is no shell expansion unless your command starts a shell itself. Put
@@ -190,6 +194,11 @@ herdr plugin log list --plugin example.layout
 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.
+Installed and linked plugins, including their enabled state, are global to the
+current user and available in every Herdr session. Both `plugin install` and
+`plugin link` can register plugins while no Herdr server is running. Plugins
+installed only in a named session on Herdr 0.7.3 must be installed or linked
+again. Existing plugin config and state remain in place.
 Installing over a locally linked plugin is refused; unlink or uninstall the
 local plugin first. `plugin install` and `plugin link` create the plugin's
 config and state directories, and `plugin config-dir <id>` prints the config
@@ -222,6 +231,24 @@ plugin context or Herdr socket env. Plugin authors should document required
 system tools such as `cargo`, `npm`, `bun`, or `lua`; Herdr reports build
 failures but does not install missing toolchains.
 
+## Startup hooks
+
+`[[startup]]` commands run once for each enabled plugin after Herdr restores the
+session and its API socket is ready. They run again when a new server takes over
+during live handoff, but not when a client attaches, config reloads, or a plugin
+is linked or enabled. Herdr starts them asynchronously and records their
+completion in the normal plugin command log. A startup failure does not stop the
+server.
+
+Startup hooks are one-shot initialization commands, not supervised daemons. A
+hook should restore plugin-owned state, call any required Herdr APIs, and exit.
+For example, a plugin can save a declarative Agent view under
+`HERDR_PLUGIN_STATE_DIR`, then read and reapply that view from its startup hook.
+
+Startup hooks receive the normal runtime plugin environment and
+`HERDR_PLUGIN_EVENT=startup`. The install preview lists every startup command so
+users can review code that will run automatically.
+
 ## Commands and environment
 
 Runtime commands run with the plugin directory as their working directory. Herdr
@@ -229,8 +256,10 @@ injects `HERDR_SOCKET_PATH`, `HERDR_BIN_PATH`, `HERDR_ENV=1`,
 `HERDR_PLUGIN_ID`, `HERDR_PLUGIN_ROOT`, `HERDR_PLUGIN_CONFIG_DIR`,
 `HERDR_PLUGIN_STATE_DIR`, `HERDR_PLUGIN_CONTEXT_JSON`, and any available
 `HERDR_WORKSPACE_ID`, `HERDR_TAB_ID`, and `HERDR_PANE_ID`. Action commands also
-receive `HERDR_PLUGIN_ACTION_ID`; event hooks receive `HERDR_PLUGIN_EVENT` and
-`HERDR_PLUGIN_EVENT_JSON`; pane commands receive `HERDR_PLUGIN_ENTRYPOINT_ID`.
+receive `HERDR_PLUGIN_ACTION_ID`; startup and event hooks receive
+`HERDR_PLUGIN_EVENT` (`startup` for startup hooks), event hooks additionally
+receive `HERDR_PLUGIN_EVENT_JSON`, and pane commands receive
+`HERDR_PLUGIN_ENTRYPOINT_ID`.
 
 `HERDR_PLUGIN_ROOT` is the installed or linked plugin directory. Do not store
 user credentials or durable state there, because GitHub-installed plugin roots