docs: add plugin trust and security guidance

2 files changed, 23 insertions, 2 deletions

diff --git a/docs/next/website/src/content/docs/marketplace.mdx b/docs/next/website/src/content/docs/marketplace.mdx
index be662b8a..f07b8f87 100644
--- a/docs/next/website/src/content/docs/marketplace.mdx
+++ b/docs/next/website/src/content/docs/marketplace.mdx
@@ -33,5 +33,7 @@ declared `platforms`, and a link back to the source repository. Getting that
 manifest metadata right today is what makes your listing accurate later. Declare
 `platforms` honestly, because the index will use it to show where a plugin runs.
 
-Plugins stay ordinary GitHub repositories. The marketplace is a discovery and
-trust layer on top of the same `herdr plugin install` path you can use now.
+Plugins stay ordinary GitHub repositories. The marketplace is a discovery layer
+on top of the same `herdr plugin install` path you can use now. A listing makes a
+plugin easier to find; it does not mean Herdr has reviewed it, so the
+[trust guidance](/docs/plugins/#trust-and-security) still applies.
diff --git a/docs/next/website/src/content/docs/plugins.mdx b/docs/next/website/src/content/docs/plugins.mdx
index 09d89bc0..9f069fdf 100644
--- a/docs/next/website/src/content/docs/plugins.mdx
+++ b/docs/next/website/src/content/docs/plugins.mdx
@@ -33,6 +33,25 @@ Runtime action registration and native non-terminal plugin UI are not part of
 plugin v1. Actions, event hooks, panes, and link handlers are all declared in
 the manifest.
 
+## Trust and security
+
+A plugin is ordinary code that runs on your machine. When you install or link
+one, its build and runtime commands run as your user, with your environment, and
+can call the full Herdr CLI — the same as any extension you add to an editor,
+shell, or coding agent. That openness is the point, and a little judgment keeps
+it safe.
+
+Install plugins from authors and repositories you trust, and skim what a new one
+does first: the `herdr-plugin.toml` manifest and the scripts or binaries it runs.
+`herdr plugin install` shows a preview of the source and the commands it will run
+in interactive terminals, so you can review before confirming. Use `--yes` for
+sources you already trust, and pin `--ref` when you want a specific revision.
+
+Herdr validates the manifest and keeps each plugin's config and state in its own
+directory, but it does not review or sandbox what a plugin does. Third-party
+plugins come from their authors, not from Herdr, so they are yours to vet and run
+at your own discretion.
+
 ## Manifest
 
 The manifest is the contract between Herdr and the plugin. It declares package