diff --git a/website/docs/developer-guide/adding-tools.md b/website/docs/developer-guide/adding-tools.md
index 0fe6d795ae4..975bdaca060 100644
--- a/website/docs/developer-guide/adding-tools.md
+++ b/website/docs/developer-guide/adding-tools.md
@@ -14,7 +14,7 @@ If you want a personal, project-local, or otherwise custom tool without
 modifying Hermes core, use the plugin route instead:
 
 - [Plugins](/user-guide/features/plugins)
-- [Build a Hermes Plugin](/guides/build-a-hermes-plugin)
+- [Build a Hermes Plugin](/developer-guide/plugins)
 
 Default to plugins for most custom tool creation. Only follow this page when
 you explicitly want to ship a new built-in tool in `tools/` and `toolsets.py`.
diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md
index f3698f8e52a..6d6ec8695ae 100644
--- a/website/docs/developer-guide/architecture.md
+++ b/website/docs/developer-guide/architecture.md
@@ -231,7 +231,7 @@ Long-running process with 20 platform adapters, unified session routing, user au
 
 Three discovery sources: `~/.hermes/plugins/` (user), `.hermes/plugins/` (project), and pip entry points. Plugins register tools, hooks, and CLI commands through a context API. Two specialized plugin types exist: memory providers (`plugins/memory/`) and context engines (`plugins/context_engine/`). Both are single-select — only one of each can be active at a time, configured via `hermes plugins` or `config.yaml`.
 
-→ [Plugin Guide](/guides/build-a-hermes-plugin), [Memory Provider Plugin](./memory-provider-plugin.md)
+→ [Plugin Guide](/developer-guide/plugins), [Memory Provider Plugin](./memory-provider-plugin.md)
 
 ### Cron
 
diff --git a/website/docs/developer-guide/contributing.md b/website/docs/developer-guide/contributing.md
index e9cc9629cda..52ec92d28ad 100644
--- a/website/docs/developer-guide/contributing.md
+++ b/website/docs/developer-guide/contributing.md
@@ -22,7 +22,7 @@ We value contributions in this order:
 
 ## Common contribution paths
 
-- Building a custom/local tool without modifying Hermes core? Start with [Build a Hermes Plugin](../guides/build-a-hermes-plugin.md)
+- Building a custom/local tool without modifying Hermes core? Start with [Build a Hermes Plugin](../developer-guide/plugins/index.md)
 - Building a new built-in core tool for Hermes itself? Start with [Adding Tools](./adding-tools.md)
 - Building a new skill? Start with [Creating Skills](./creating-skills.md)
 - Building a new inference provider? Start with [Adding Providers](./adding-providers.md)
diff --git a/website/docs/developer-guide/image-gen-provider-plugin.md b/website/docs/developer-guide/image-gen-provider-plugin.md
index b746ce82229..66179cfa5c0 100644
--- a/website/docs/developer-guide/image-gen-provider-plugin.md
+++ b/website/docs/developer-guide/image-gen-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build an image-generation backend plugin for Hermes Agent"
 Image-gen provider plugins register a backend that services every `image_generate` tool call — DALL·E, gpt-image, Grok, Flux, Imagen, Stable Diffusion, fal, Replicate, a local ComfyUI rig, anything. Built-in providers (OpenAI, OpenAI-Codex, xAI) all ship as plugins. You can add a new one, or override a bundled one, by dropping a directory into `plugins/image_gen/<name>/`.
 
 :::tip
-Image-gen is one of several **backend plugins** Hermes supports. The others (with more specialized ABCs) are [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/guides/build-a-hermes-plugin).
+Image-gen is one of several **backend plugins** Hermes supports. The others (with more specialized ABCs) are [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
 :::
 
 ## How discovery works
@@ -307,10 +307,10 @@ Or interactively: `hermes tools` → "Image Generation" → select `my-backend`
 my-backend-imggen = "my_backend_imggen_package"
 ```
 
-`my_backend_imggen_package` must expose a top-level `register` function. See [Distribute via pip](/guides/build-a-hermes-plugin#distribute-via-pip) in the general plugin guide for the full setup.
+`my_backend_imggen_package` must expose a top-level `register` function. See [Distribute via pip](/developer-guide/plugins#distribute-via-pip) in the general plugin guide for the full setup.
 
 ## Related pages
 
 - [Image Generation](/user-guide/features/image-generation) — user-facing feature documentation
 - [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance
-- [Build a Hermes Plugin](/guides/build-a-hermes-plugin) — general tools/hooks/slash commands guide
+- [Build a Hermes Plugin](/developer-guide/plugins) — general tools/hooks/slash commands guide
diff --git a/website/docs/developer-guide/model-provider-plugin.md b/website/docs/developer-guide/model-provider-plugin.md
index f12ed3abf33..6c20a66be42 100644
--- a/website/docs/developer-guide/model-provider-plugin.md
+++ b/website/docs/developer-guide/model-provider-plugin.md
@@ -257,7 +257,7 @@ acme-inference = "acme_hermes_plugin:register"
 
 …where `acme_hermes_plugin:register` is a function that calls `register_provider(profile)`. The general PluginManager picks up entry-point plugins during `discover_and_load()`. For `kind: model-provider` pip plugins, you still need to declare the kind in your manifest (or rely on the source-text heuristic).
 
-See [Building a Hermes Plugin](/guides/build-a-hermes-plugin#distribute-via-pip) for the full entry-points setup.
+See [Building a Hermes Plugin](/developer-guide/plugins#distribute-via-pip) for the full entry-points setup.
 
 ## Related pages
 
@@ -265,4 +265,4 @@ See [Building a Hermes Plugin](/guides/build-a-hermes-plugin#distribute-via-pip)
 - [Adding Providers](/developer-guide/adding-providers) — end-to-end checklist for new inference backends (covers both the fast plugin path and the full CLI/auth integration)
 - [Memory Provider Plugins](/developer-guide/memory-provider-plugin)
 - [Context Engine Plugins](/developer-guide/context-engine-plugin)
-- [Building a Hermes Plugin](/guides/build-a-hermes-plugin) — general plugin authoring
+- [Building a Hermes Plugin](/developer-guide/plugins) — general plugin authoring
diff --git a/website/docs/guides/build-a-hermes-plugin.md b/website/docs/developer-guide/plugins/index.md
similarity index 99%
rename from website/docs/guides/build-a-hermes-plugin.md
rename to website/docs/developer-guide/plugins/index.md
index 8c8f139b4ff..1fa5d1c5e20 100644
--- a/website/docs/guides/build-a-hermes-plugin.md
+++ b/website/docs/developer-guide/plugins/index.md
@@ -1,6 +1,6 @@
 ---
-sidebar_position: 9
 sidebar_label: "Build a Plugin"
+slug: /developer-guide/plugins
 title: "Build a Hermes Plugin"
 description: "Step-by-step guide to building a complete Hermes plugin with tools, hooks, data files, and skills"
 ---
diff --git a/website/docs/developer-guide/secret-source-plugin.md b/website/docs/developer-guide/secret-source-plugin.md
new file mode 100644
index 00000000000..aeecc96053e
--- /dev/null
+++ b/website/docs/developer-guide/secret-source-plugin.md
@@ -0,0 +1,171 @@
+---
+sidebar_position: 9
+title: "Secret Source Plugins"
+description: "How to build a secret-manager backend plugin for Hermes Agent"
+---
+
+# Building a Secret Source Plugin
+
+Secret sources resolve provider credentials from an external secret manager (a vault, a password manager, an OS keystore, a custom script) into environment variables at process startup — after `~/.hermes/.env` loads, before Hermes reads credentials. Bitwarden and 1Password ship in-tree; **every other backend is a plugin**. This guide covers building one.
+
+:::tip
+The bundled set is deliberately closed, same policy as [memory providers](/developer-guide/memory-provider-plugin): PRs adding new vault backends under `agent/secret_sources/` are closed with a pointer to this guide. Publish your backend as a standalone plugin repo and share it in the Nous Research Discord (`#plugins-skills-and-skins`).
+:::
+
+## What the framework owns vs. what you own
+
+The orchestrator (`agent.secret_sources.registry.apply_all`) owns everything security- and precedence-sensitive, so a backend cannot get it wrong:
+
+| Framework owns | You own |
+|---|---|
+| Source ordering, mapped-vs-bulk precedence | Fetching values from your backend |
+| First-claim-wins conflict handling + warnings | Validating your reference format |
+| `override_existing` semantics (never crosses sources) | Talking to your CLI/SDK/API |
+| Protected bootstrap tokens | Declaring which env var IS your bootstrap token |
+| Per-source wall-clock timeout | Keeping `fetch()` reasonably fast |
+| Per-var provenance + `(from X)` labels | A human-readable `label` |
+| `os.environ` writes | Nothing — you never touch the environment |
+
+## Directory structure
+
+```
+~/.hermes/plugins/my-vault/
+├── plugin.yaml      # name, description
+└── __init__.py      # SecretSource subclass + register(ctx)
+```
+
+## The SecretSource ABC
+
+Implement `agent.secret_sources.base.SecretSource`. One method is required:
+
+```python
+from pathlib import Path
+
+from agent.secret_sources.base import (
+    ErrorKind,
+    FetchResult,
+    SecretSource,
+    run_secret_cli,
+)
+
+
+class MyVaultSource(SecretSource):
+    name = "myvault"          # config section key: secrets.myvault
+    label = "My Vault"        # used in startup lines + provenance labels
+    shape = "mapped"          # "mapped" (explicit VAR→ref map) or "bulk" (project dump)
+    scheme = "mv"             # optional: unique URI scheme you own (mv://...)
+
+    def fetch(self, cfg: dict, home_path: Path) -> FetchResult:
+        """Resolve secrets. MUST NOT raise. MUST NOT prompt."""
+        result = FetchResult()
+        token = os.environ.get("MYVAULT_TOKEN", "").strip()
+        if not token:
+            result.error = "secrets.myvault.enabled is true but MYVAULT_TOKEN is not set."
+            result.error_kind = ErrorKind.NOT_CONFIGURED
+            return result
+
+        try:
+            proc = run_secret_cli(
+                ["myvault-cli", "export", "--json"],
+                allow_env=["MYVAULT_TOKEN"],   # ONLY your auth vars — never full os.environ
+                timeout=30,
+            )
+        except RuntimeError as exc:           # spawn failure / timeout
+            result.error = str(exc)
+            result.error_kind = ErrorKind.BINARY_MISSING
+            return result
+
+        if proc.returncode != 0:
+            result.error = f"myvault-cli exited {proc.returncode}: {proc.stderr[:200]}"
+            result.error_kind = ErrorKind.AUTH_FAILED
+            return result
+
+        result.secrets = parse_your_output(proc.stdout)  # {ENV_VAR: value}
+        return result
+
+    def protected_env_vars(self, cfg: dict):
+        # Your bootstrap token — no source (including yours) may ever overwrite it.
+        return frozenset({"MYVAULT_TOKEN"})
+```
+
+### Contract rules (enforced, not suggestions)
+
+- **`fetch()` never raises.** Errors go in `result.error` + `result.error_kind`. A raising fetch is contained by the orchestrator and reported as `INTERNAL` — a contract violation, not a feature.
+- **`fetch()` never prompts.** Startup runs in non-TTY contexts (gateway, cron, Docker). `run_secret_cli()` closes stdin so a prompting helper fails fast. Interactive auth belongs in your CLI setup flow, never on the startup path.
+- **Sync, within budget.** The orchestrator enforces a wall-clock timeout (default 120s, user-tunable via `secrets.<name>.timeout_seconds`). Exceeding it reports `TIMEOUT` and your result is discarded.
+- **You fetch; the orchestrator applies.** Return the mapping you *would* contribute. Never write `os.environ` yourself — you'd bypass precedence, conflict detection, and provenance.
+- **API versioning.** `SecretSource.api_version` defaults to the current `SECRET_SOURCE_API_VERSION`. The registry skips (with a warning) sources built against a different version instead of crashing startup.
+
+### Choosing your `shape`
+
+- `mapped` — the user explicitly binds env-var names to references in config (like 1Password's `env:` map). Strongest intent: mapped claims beat bulk claims on contested vars.
+- `bulk` — you inject a whole project/folder of secrets implicitly (like Bitwarden BSM). Yields to mapped sources.
+
+### Optional hooks
+
+| Method | Default | Override when |
+|---|---|---|
+| `is_enabled(cfg)` | `cfg.get("enabled")` | Custom activation logic |
+| `override_existing(cfg)` | `cfg.get("override_existing", False)` | You want a different default (both bundled sources default `True` for rotation) |
+| `protected_env_vars(cfg)` | empty | You have a bootstrap token (you almost certainly do) |
+| `fetch_timeout_seconds(cfg)` | 120s | Your backend needs a different budget |
+| `config_schema()` | `{}` | Declare config keys for setup surfaces |
+
+## Subprocess safety: use `run_secret_cli()`
+
+If your backend shells out to a CLI, use the shared helper instead of `subprocess.run` directly. It gives you the audited posture for free: argv-only (no `shell=True`), a **minimal allowlisted child environment** (by the time sources run, `os.environ` holds every credential Hermes knows — never hand that to a child process), `NO_COLOR` + ANSI-scrubbed stderr, stdin closed, timeout → clean `RuntimeError`. Pass user-supplied reference strings after a `--` terminator in your argv so they can never parse as flags.
+
+## Registering
+
+```python
+# __init__.py
+def register(ctx):
+    ctx.register_secret_source(MyVaultSource())
+```
+
+Registration is rejected (with a log warning, never a crash) for: non-`SecretSource` instances, invalid/duplicate names, a `scheme` another source owns, wrong `api_version`, or a `shape` outside `mapped`/`bulk`.
+
+:::note Timing
+Plugin discovery runs later in startup than the first `load_hermes_dotenv()` call, so a plugin source is not consulted by the very first env load of the process that discovers it. It IS consulted by every subsequently spawned Hermes process (gateway children, cron sessions, subagents). Bundled sources cover first-process bootstrap.
+:::
+
+## Users configure it like any other source
+
+```yaml
+secrets:
+  sources: [myvault, bitwarden]   # optional ordering
+  myvault:
+    enabled: true
+    # ... your config_schema keys
+```
+
+Multi-source precedence, conflict warnings, and `(from My Vault)` provenance labels all work automatically — see the [user-facing secrets docs](/user-guide/secrets/) for the precedence ladder.
+
+## Validate with the conformance kit
+
+Subclass the kit from the Hermes repo (`tests/secret_sources/conformance.py`) in your plugin's tests:
+
+```python
+import pytest
+from tests.secret_sources.conformance import SecretSourceConformance
+
+class TestMyVaultConformance(SecretSourceConformance):
+    @pytest.fixture
+    def source(self):
+        return MyVaultSource()
+```
+
+It checks the rules that break other people when violated: never-raises on malformed config, machine-readable error kinds, disabled-by-default, positive timeouts, valid protected-var names, and a full `apply_all()` round trip. Green conformance is the review bar for calling a backend contract-compliant.
+
+## ErrorKind reference
+
+| Kind | Meaning |
+|---|---|
+| `NOT_CONFIGURED` | Enabled but missing token / project / map |
+| `BINARY_MISSING` | Helper CLI not found or not executable |
+| `AUTH_FAILED` / `AUTH_EXPIRED` | Bad / expired credentials |
+| `REF_INVALID` | A secret reference failed validation |
+| `NETWORK` | Transport-level failure |
+| `EMPTY_VALUE` | Backend returned nothing for a ref — never apply `""` over a good credential |
+| `TIMEOUT` | Fetch exceeded its budget |
+| `INTERNAL` | Anything else (bug, unexpected shape) |
diff --git a/website/docs/developer-guide/web-search-provider-plugin.md b/website/docs/developer-guide/web-search-provider-plugin.md
index 880cad8886e..4f880866c69 100644
--- a/website/docs/developer-guide/web-search-provider-plugin.md
+++ b/website/docs/developer-guide/web-search-provider-plugin.md
@@ -9,7 +9,7 @@ description: "How to build a web-search/extract/crawl backend plugin for Hermes
 Web-search provider plugins register a backend that services `web_search`, `web_extract`, and (optionally) deep-crawl tool calls. Built-in providers — Firecrawl, SearXNG, Tavily, Exa, Parallel, Brave Search (free tier), xAI, and DDGS — all ship as plugins under `plugins/web/<name>/`. You can add a new one, or override a bundled one, by dropping a directory next to them.
 
 :::tip
-Web search is one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin), [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin), [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/guides/build-a-hermes-plugin).
+Web search is one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin), [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin), [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
 :::
 
 ## How discovery works
@@ -141,7 +141,7 @@ requires_env:
 |---|---|
 | `kind: backend` | Routes the plugin through the backend-loading path |
 | `provides_web_providers` | List of provider `name`s this plugin registers — used by the loader to advertise the plugin in `hermes tools` even before `register()` runs |
-| `requires_env` | Interactive credential prompt during `hermes plugins install` (see [Build a Hermes Plugin](/guides/build-a-hermes-plugin#gate-on-environment-variables) for the rich format) |
+| `requires_env` | Interactive credential prompt during `hermes plugins install` (see [Build a Hermes Plugin](/developer-guide/plugins#gate-on-environment-variables) for the rich format) |
 
 ## ABC reference
 
@@ -233,7 +233,7 @@ Errors surface as the tool result; the LLM decides how to explain them. If no pr
 
 ## Lazy-installing optional dependencies
 
-If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package), don't `import` it at module top level. Use `tools.lazy_deps.ensure(...)` inside `is_available()` or `search()` — Hermes will install the package on first use, gated by `security.allow_lazy_installs`. See [Build a Hermes Plugin → Lazy-install](/guides/build-a-hermes-plugin#lazy-install-optional-python-dependencies) for the security model.
+If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package), don't `import` it at module top level. Use `tools.lazy_deps.ensure(...)` inside `is_available()` or `search()` — Hermes will install the package on first use, gated by `security.allow_lazy_installs`. See [Build a Hermes Plugin → Lazy-install](/developer-guide/plugins#lazy-install-optional-python-dependencies) for the security model.
 
 ## Reference implementations
 
@@ -251,10 +251,10 @@ If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package
 my-backend-web = "my_backend_web_package"
 ```
 
-`my_backend_web_package` must expose a top-level `register` function. See [Distribute via pip](/guides/build-a-hermes-plugin#distribute-via-pip) in the general plugin guide for the full setup.
+`my_backend_web_package` must expose a top-level `register` function. See [Distribute via pip](/developer-guide/plugins#distribute-via-pip) in the general plugin guide for the full setup.
 
 ## Related pages
 
 - [Web Search](/user-guide/features/web-search) — user-facing feature documentation and per-backend configuration
 - [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance
-- [Build a Hermes Plugin](/guides/build-a-hermes-plugin) — general tools/hooks/slash commands guide
+- [Build a Hermes Plugin](/developer-guide/plugins) — general tools/hooks/slash commands guide
diff --git a/website/docs/getting-started/learning-path.md b/website/docs/getting-started/learning-path.md
index 619e2010394..a643267637a 100644
--- a/website/docs/getting-started/learning-path.md
+++ b/website/docs/getting-started/learning-path.md
@@ -85,7 +85,7 @@ Cron jobs let Hermes Agent run tasks on a schedule — daily summaries, periodic
 Extend Hermes Agent with your own tools and reusable skill packages.
 
 1. [Plugins](/user-guide/features/plugins)
-2. [Build a Hermes Plugin](/guides/build-a-hermes-plugin)
+2. [Build a Hermes Plugin](/developer-guide/plugins)
 3. [Tools Overview](/user-guide/features/tools)
 4. [Skills Overview](/user-guide/features/skills)
 5. [MCP (Model Context Protocol)](/user-guide/features/mcp)
diff --git a/website/docs/guides/github-pr-review-agent.md b/website/docs/guides/github-pr-review-agent.md
index b5fe0a525b2..f45684973bd 100644
--- a/website/docs/guides/github-pr-review-agent.md
+++ b/website/docs/guides/github-pr-review-agent.md
@@ -298,6 +298,6 @@ GitHub allows 5,000 API requests/hour for authenticated users. Each PR review us
 
 - **[Webhook-Based PR Reviews](./webhook-github-pr-review.md)** — get instant reviews when PRs are opened (requires a public endpoint)
 - **[Daily Briefing Bot](/guides/daily-briefing-bot)** — combine PR reviews with your morning news digest
-- **[Build a Plugin](/guides/build-a-hermes-plugin)** — wrap the review logic into a shareable plugin
+- **[Build a Plugin](/developer-guide/plugins)** — wrap the review logic into a shareable plugin
 - **[Profiles](/user-guide/profiles)** — run a dedicated reviewer profile with its own memory and config
 - **[Fallback Providers](/user-guide/features/fallback-providers)** — ensure reviews run even when one provider is down
diff --git a/website/docs/guides/webhook-github-pr-review.md b/website/docs/guides/webhook-github-pr-review.md
index f3f3666e2c4..8c0551a5af1 100644
--- a/website/docs/guides/webhook-github-pr-review.md
+++ b/website/docs/guides/webhook-github-pr-review.md
@@ -325,5 +325,5 @@ platforms:
 
 - **[Cron-Based PR Reviews](./github-pr-review-agent.md)** — poll for PRs on a schedule, no public endpoint needed
 - **[Webhook Reference](/user-guide/messaging/webhooks)** — full config reference for the webhook platform
-- **[Build a Plugin](/guides/build-a-hermes-plugin)** — package review logic into a shareable plugin
+- **[Build a Plugin](/developer-guide/plugins)** — package review logic into a shareable plugin
 - **[Profiles](/user-guide/profiles)** — run a dedicated reviewer profile with its own memory and config
diff --git a/website/docs/guides/work-with-skills.md b/website/docs/guides/work-with-skills.md
index 331558924e0..f191ff146d1 100644
--- a/website/docs/guides/work-with-skills.md
+++ b/website/docs/guides/work-with-skills.md
@@ -135,7 +135,7 @@ skill_view("writing-plans")
 
 Plugin skills are **not** listed in the system prompt and don't appear in `skills_list`. They're opt-in — load them explicitly when you know a plugin provides one. When loaded, the agent sees a banner listing sibling skills from the same plugin.
 
-For how to ship skills in your own plugin, see [Build a Hermes Plugin → Bundle skills](/guides/build-a-hermes-plugin#bundle-skills).
+For how to ship skills in your own plugin, see [Build a Hermes Plugin → Bundle skills](/developer-guide/plugins#bundle-skills).
 
 ---
 
diff --git a/website/docs/integrations/index.md b/website/docs/integrations/index.md
index e3389b33abd..90bd0a4042a 100644
--- a/website/docs/integrations/index.md
+++ b/website/docs/integrations/index.md
@@ -102,7 +102,7 @@ See the [Messaging Gateway overview](/user-guide/messaging) for the platform com
 ## Plugins
 
 - **[Plugin System](/user-guide/features/plugins)** — Extend Hermes with custom tools, lifecycle hooks, and CLI commands without modifying core code. Plugins are discovered from `~/.hermes/plugins/`, project-local `.hermes/plugins/`, and pip-installed entry points.
-- **[Build a Plugin](/guides/build-a-hermes-plugin)** — Step-by-step guide for creating Hermes plugins with tools, hooks, and CLI commands.
+- **[Build a Plugin](/developer-guide/plugins)** — Step-by-step guide for creating Hermes plugins with tools, hooks, and CLI commands.
 
 ## Training & Evaluation
 
diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md
index 69e9d702253..1bc4d4b131b 100644
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -1289,7 +1289,7 @@ Provider plugin selections are saved to `config.yaml`:
 
 General plugin disabled list is stored in `config.yaml` under `plugins.disabled`.
 
-See [Plugins](../user-guide/features/plugins.md) and [Build a Hermes Plugin](../guides/build-a-hermes-plugin.md).
+See [Plugins](../user-guide/features/plugins.md) and [Build a Hermes Plugin](../developer-guide/plugins/index.md).
 
 ## `hermes tools`
 
diff --git a/website/docs/user-guide/features/built-in-plugins.md b/website/docs/user-guide/features/built-in-plugins.md
index b4c1d5ef080..722105fcf67 100644
--- a/website/docs/user-guide/features/built-in-plugins.md
+++ b/website/docs/user-guide/features/built-in-plugins.md
@@ -9,7 +9,7 @@ description: "Plugins shipped with Hermes Agent that run automatically via lifec
 
 Hermes ships a small set of plugins bundled with the repository. They live under `<repo>/plugins/<name>/` and load automatically alongside user-installed plugins in `~/.hermes/plugins/`. They use the same plugin surface as third-party plugins — hooks, tools, slash commands — just maintained in-tree.
 
-See the [Plugins](/user-guide/features/plugins) page for the general plugin system, and [Build a Hermes Plugin](/guides/build-a-hermes-plugin) to write your own.
+See the [Plugins](/user-guide/features/plugins) page for the general plugin system, and [Build a Hermes Plugin](/developer-guide/plugins) to write your own.
 
 ## How discovery works
 
@@ -286,7 +286,7 @@ Adds a **Steam-style achievements tab to the dashboard** — 60+ collectible, ti
 
 ## Adding a bundled plugin
 
-Bundled plugins are written exactly like any other Hermes plugin — see [Build a Hermes Plugin](/guides/build-a-hermes-plugin). The only differences are:
+Bundled plugins are written exactly like any other Hermes plugin — see [Build a Hermes Plugin](/developer-guide/plugins). The only differences are:
 
 - Directory lives at `<repo>/plugins/<name>/` instead of `~/.hermes/plugins/<name>/`
 - Manifest source is reported as `bundled` in `hermes plugins list`
diff --git a/website/docs/user-guide/features/hooks.md b/website/docs/user-guide/features/hooks.md
index 4a2fc068606..224d20198b3 100644
--- a/website/docs/user-guide/features/hooks.md
+++ b/website/docs/user-guide/features/hooks.md
@@ -873,7 +873,7 @@ def my_callback(session_id: str, platform: str, **kwargs):
 
 ---
 
-See the **[Build a Plugin guide](/guides/build-a-hermes-plugin)** for the full walkthrough including tool schemas, handlers, and advanced hook patterns.
+See the **[Build a Plugin guide](/developer-guide/plugins)** for the full walkthrough including tool schemas, handlers, and advanced hook patterns.
 
 ---
 
diff --git a/website/docs/user-guide/features/plugins.md b/website/docs/user-guide/features/plugins.md
index f543b5610a2..ed8012325b6 100644
--- a/website/docs/user-guide/features/plugins.md
+++ b/website/docs/user-guide/features/plugins.md
@@ -14,7 +14,7 @@ this is usually the right path. The developer guide's
 [Adding Tools](/developer-guide/adding-tools) page is for built-in Hermes
 core tools that live in `tools/` and `toolsets.py`.
 
-**→ [Build a Hermes Plugin](/guides/build-a-hermes-plugin)** — step-by-step guide with a complete working example.
+**→ [Build a Hermes Plugin](/developer-guide/plugins)** — step-by-step guide with a complete working example.
 
 ## Quick overview
 
@@ -221,9 +221,9 @@ The table above shows the four plugin categories, but within "General plugins" t
 
 | Want to add… | How | Authoring guide |
 |---|---|---|
-| A **tool** the LLM can call | Python plugin — `ctx.register_tool()` | [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Adding Tools](/developer-guide/adding-tools) |
-| A **lifecycle hook** (pre/post LLM, session start/end, tool filter) | Python plugin — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/guides/build-a-hermes-plugin) |
-| A **slash command** for the CLI / gateway | Python plugin — `ctx.register_command()` | [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Extending the CLI](/developer-guide/extending-the-cli) |
+| A **tool** the LLM can call | Python plugin — `ctx.register_tool()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Adding Tools](/developer-guide/adding-tools) |
+| A **lifecycle hook** (pre/post LLM, session start/end, tool filter) | Python plugin — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/developer-guide/plugins) |
+| A **slash command** for the CLI / gateway | Python plugin — `ctx.register_command()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Extending the CLI](/developer-guide/extending-the-cli) |
 | A **subcommand** for `hermes <thing>` | Python plugin — `ctx.register_cli_command()` | [Extending the CLI](/developer-guide/extending-the-cli) |
 | A bundled **skill** that your plugin ships | Python plugin — `ctx.register_skill()` | [Creating Skills](/developer-guide/creating-skills) |
 | An **inference backend** (LLM provider: OpenAI-compat, Codex, Anthropic-Messages, Bedrock) | Provider plugin — `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/` | **[Model Provider Plugins](/developer-guide/model-provider-plugin)** · [Adding Providers](/developer-guide/adding-providers) |
@@ -343,4 +343,4 @@ This enables plugins like remote control viewers, messaging bridges, or webhook
 `inject_message` is only available in CLI mode. In gateway mode, there is no CLI reference and the method returns `False`.
 :::
 
-See the **[full guide](/guides/build-a-hermes-plugin)** for handler contracts, schema format, hook behavior, error handling, and common mistakes.
+See the **[full guide](/developer-guide/plugins)** for handler contracts, schema format, hook behavior, error handling, and common mistakes.
diff --git a/website/docs/user-guide/secrets/index.md b/website/docs/user-guide/secrets/index.md
index 6e14b2d3846..2e39a31057c 100644
--- a/website/docs/user-guide/secrets/index.md
+++ b/website/docs/user-guide/secrets/index.md
@@ -29,6 +29,6 @@ Every credential injected by a source is labelled with its origin — setup flow
 
 ## Adding your own backend
 
-Third-party secret managers ship as standalone plugins, not core PRs. A backend subclasses `agent.secret_sources.base.SecretSource` (one required method: `fetch(cfg, home_path) -> FetchResult`) and registers via `ctx.register_secret_source(MySource())` in the plugin's `register(ctx)`. The orchestrator owns precedence, conflict handling, timeouts, and provenance — your source only fetches. Contract rules: `fetch()` never raises, never prompts, and returns within its timeout budget; validate your implementation against the conformance kit in `tests/secret_sources/conformance.py`.
+Third-party secret managers ship as standalone plugins, not core PRs. A backend subclasses `agent.secret_sources.base.SecretSource` (one required method: `fetch(cfg, home_path) -> FetchResult`) and registers via `ctx.register_secret_source(MySource())` in the plugin's `register(ctx)`. The orchestrator owns precedence, conflict handling, timeouts, and provenance — your source only fetches. Full guide with the contract rules, subprocess-safety helper, and conformance kit: [Building a Secret Source Plugin](/developer-guide/secret-source-plugin).
 
 The bundled set is deliberately closed (same policy as memory providers): Bitwarden and 1Password ship in-tree. Everything else — Infisical, Proton Pass, HashiCorp Vault, AWS Secrets Manager, OS keystores — belongs in plugin repos; share them in the Nous Research Discord (`#plugins-skills-and-skins`).
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index 6b2e35aa864..6243170a6b9 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -78,6 +78,12 @@ const config: Config = {
             from: '/guides/automation-templates',
             to: '/guides/automation-blueprints',
           },
+          {
+            // Moved when the Plugins subcategory was created under
+            // Developer Guide > Extending (docs restructure, July 2026)
+            from: '/guides/build-a-hermes-plugin',
+            to: '/developer-guide/plugins',
+          },
         ],
       },
     ],
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md
index 21aaff76ca8..bc9eb457ec8 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/adding-tools.md
@@ -13,7 +13,7 @@ description: "如何向 Hermes Agent 添加新工具——schema、handler、注
 如果你想要个人专用、项目本地或其他自定义工具，而不修改 Hermes 核心，请使用插件方式：
 
 - [插件](/user-guide/features/plugins)
-- [构建 Hermes 插件](/guides/build-a-hermes-plugin)
+- [构建 Hermes 插件](/developer-guide/plugins)
 
 大多数自定义工具创建场景默认使用插件。只有当你明确希望在 `tools/` 和 `toolsets.py` 中发布新的内置工具时，才遵循本页面。
 :::
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md
index f5c6c71ffbb..5b3ba00aa3b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/architecture.md
@@ -231,7 +231,7 @@ CLI、gateway、cron、ACP 及辅助调用共用的运行时解析器。将 `(pr
 
 三种发现来源：`~/.hermes/plugins/`（用户级）、`.hermes/plugins/`（项目级）和 pip entry point。插件通过上下文 API 注册工具、hook 和 CLI 命令。存在两种专用插件类型：记忆提供者（`plugins/memory/`）和上下文引擎（`plugins/context_engine/`）。两者均为单选——每种同时只能激活一个，通过 `hermes plugins` 或 `config.yaml` 配置。
 
-→ [插件指南](/guides/build-a-hermes-plugin)，[记忆提供者插件](./memory-provider-plugin.md)
+→ [插件指南](/developer-guide/plugins)，[记忆提供者插件](./memory-provider-plugin.md)
 
 ### Cron
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md
index 773017012a6..8a4547f35d5 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md
@@ -22,7 +22,7 @@ description: "如何为 Hermes Agent 做贡献 — 开发环境配置、代码
 
 ## 常见贡献路径
 
-- 构建自定义/本地工具而不修改 Hermes 核心？从 [构建 Hermes 插件](../guides/build-a-hermes-plugin.md) 开始
+- 构建自定义/本地工具而不修改 Hermes 核心？从 [构建 Hermes 插件](../developer-guide/plugins/index.md) 开始
 - 为 Hermes 本身构建新的内置核心工具？从 [添加工具](./adding-tools.md) 开始
 - 构建新的 skill？从 [创建 Skill](./creating-skills.md) 开始
 - 构建新的推理提供商？从 [添加提供商](./adding-providers.md) 开始
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md
index 66bdcd1e542..60dc44bc317 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/image-gen-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建图像生成后端插件"
 图像生成 provider 插件注册一个后端，用于处理所有 `image_generate` 工具调用——DALL·E、gpt-image、Grok、Flux、Imagen、Stable Diffusion、fal、Replicate、本地 ComfyUI 装置，任何后端均可。内置 provider（OpenAI、OpenAI-Codex、xAI）均以插件形式提供。你可以通过在 `plugins/image_gen/<name>/` 目录下放置一个目录来添加新的 provider，或覆盖内置 provider。
 
 :::tip
-图像生成是 Hermes 支持的多种**后端插件**之一。其他插件（各有更专用的 ABC）包括：[Memory Provider 插件](/developer-guide/memory-provider-plugin)、[Context Engine 插件](/developer-guide/context-engine-plugin) 和 [Model Provider 插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅 [构建 Hermes 插件](/guides/build-a-hermes-plugin)。
+图像生成是 Hermes 支持的多种**后端插件**之一。其他插件（各有更专用的 ABC）包括：[Memory Provider 插件](/developer-guide/memory-provider-plugin)、[Context Engine 插件](/developer-guide/context-engine-plugin) 和 [Model Provider 插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅 [构建 Hermes 插件](/developer-guide/plugins)。
 :::
 
 ## 发现机制
@@ -279,10 +279,10 @@ hermes -z "Generate an image of a corgi in a spacesuit"
 my-backend-imggen = "my_backend_imggen_package"
 ```
 
-`my_backend_imggen_package` 必须暴露一个顶层 `register` 函数。完整配置请参阅通用插件指南中的 [通过 pip 分发](/guides/build-a-hermes-plugin#distribute-via-pip)。
+`my_backend_imggen_package` 必须暴露一个顶层 `register` 函数。完整配置请参阅通用插件指南中的 [通过 pip 分发](/developer-guide/plugins#distribute-via-pip)。
 
 ## 相关页面
 
 - [图像生成](/user-guide/features/image-generation) — 面向用户的功能文档
 - [插件概览](/user-guide/features/plugins) — 所有插件类型一览
-- [构建 Hermes 插件](/guides/build-a-hermes-plugin) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
+- [构建 Hermes 插件](/developer-guide/plugins) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md
index e649fe5d23a..3f9829c80af 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/model-provider-plugin.md
@@ -256,7 +256,7 @@ acme-inference = "acme_hermes_plugin:register"
 
 ……其中 `acme_hermes_plugin:register` 是一个调用 `register_provider(profile)` 的函数。通用 PluginManager 在 `discover_and_load()` 期间会拾取入口点插件。对于 `kind: model-provider` 的 pip 插件，你仍需在 manifest 中声明 kind（或依赖源码文本启发式检测）。
 
-完整的入口点设置请参阅 [构建 Hermes 插件](/guides/build-a-hermes-plugin#distribute-via-pip)。
+完整的入口点设置请参阅 [构建 Hermes 插件](/developer-guide/plugins#distribute-via-pip)。
 
 ## 相关页面
 
@@ -264,4 +264,4 @@ acme-inference = "acme_hermes_plugin:register"
 - [添加提供商](/developer-guide/adding-providers) — 新推理后端的端到端检查清单（涵盖快速插件路径和完整 CLI/auth 集成）
 - [Memory Provider 插件](/developer-guide/memory-provider-plugin)
 - [Context Engine 插件](/developer-guide/context-engine-plugin)
-- [构建 Hermes 插件](/guides/build-a-hermes-plugin) — 通用插件编写指南
\ No newline at end of file
+- [构建 Hermes 插件](/developer-guide/plugins) — 通用插件编写指南
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/build-a-hermes-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
similarity index 99%
rename from website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/build-a-hermes-plugin.md
rename to website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
index 19b77da2578..8ffeab09209 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/build-a-hermes-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/plugins/index.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 9
 sidebar_label: "Build a Plugin"
 title: "构建 Hermes 插件"
 description: "逐步指南：构建包含工具、钩子、数据文件和技能的完整 Hermes 插件"
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md
index 739501b0376..6d69c569f89 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/web-search-provider-plugin.md
@@ -9,7 +9,7 @@ description: "如何为 Hermes Agent 构建网页搜索/提取/爬取后端插
 网页搜索提供商插件注册一个后端，用于处理 `web_search`、`web_extract` 以及（可选的）深度爬取工具调用。内置提供商——Firecrawl、SearXNG、Tavily、Exa、Parallel、Brave Search（免费层）和 DDGS——均以插件形式存放于 `plugins/web/<name>/` 目录下。你可以在该目录旁新建一个目录来添加新提供商，或覆盖已有的内置提供商。
 
 :::tip
-网页搜索是 Hermes 支持的多种**后端插件**之一。其他插件（各有其 ABC）包括：[图像生成提供商插件](/developer-guide/image-gen-provider-plugin)、[视频生成提供商插件](/developer-guide/video-gen-provider-plugin)、[记忆提供商插件](/developer-guide/memory-provider-plugin)、[上下文引擎插件](/developer-guide/context-engine-plugin)和[模型提供商插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅[构建 Hermes 插件](/guides/build-a-hermes-plugin)。
+网页搜索是 Hermes 支持的多种**后端插件**之一。其他插件（各有其 ABC）包括：[图像生成提供商插件](/developer-guide/image-gen-provider-plugin)、[视频生成提供商插件](/developer-guide/video-gen-provider-plugin)、[记忆提供商插件](/developer-guide/memory-provider-plugin)、[上下文引擎插件](/developer-guide/context-engine-plugin)和[模型提供商插件](/developer-guide/model-provider-plugin)。通用工具/hook/CLI 插件请参阅[构建 Hermes 插件](/developer-guide/plugins)。
 :::
 
 ## 发现机制
@@ -141,7 +141,7 @@ requires_env:
 |---|---|
 | `kind: backend` | 将插件路由至后端加载路径 |
 | `provides_web_providers` | 该插件注册的提供商 `name` 列表——在 `register()` 运行之前，加载器即可通过此字段在 `hermes tools` 中公示插件 |
-| `requires_env` | 在 `hermes plugins install` 期间进行交互式凭据提示（富格式说明参见[构建 Hermes 插件](/guides/build-a-hermes-plugin#gate-on-environment-variables)） |
+| `requires_env` | 在 `hermes plugins install` 期间进行交互式凭据提示（富格式说明参见[构建 Hermes 插件](/developer-guide/plugins#gate-on-environment-variables)） |
 
 ## ABC 参考
 
@@ -233,7 +233,7 @@ web:
 
 ## 懒加载可选依赖
 
-如果你的提供商封装了第三方 SDK（如 DDGS 封装了 `ddgs` 包），请勿在模块顶层 `import`。在 `is_available()` 或 `search()` 内部使用 `tools.lazy_deps.ensure(...)` ——Hermes 将在首次使用时安装该包，并受 `security.allow_lazy_installs` 控制。安全模型详见[构建 Hermes 插件 → 懒加载](/guides/build-a-hermes-plugin#lazy-install-optional-python-dependencies)。
+如果你的提供商封装了第三方 SDK（如 DDGS 封装了 `ddgs` 包），请勿在模块顶层 `import`。在 `is_available()` 或 `search()` 内部使用 `tools.lazy_deps.ensure(...)` ——Hermes 将在首次使用时安装该包，并受 `security.allow_lazy_installs` 控制。安全模型详见[构建 Hermes 插件 → 懒加载](/developer-guide/plugins#lazy-install-optional-python-dependencies)。
 
 ## 参考实现
 
@@ -251,10 +251,10 @@ web:
 my-backend-web = "my_backend_web_package"
 ```
 
-`my_backend_web_package` 必须暴露顶层 `register` 函数。完整配置说明参见通用插件指南中的[通过 pip 分发](/guides/build-a-hermes-plugin#distribute-via-pip)。
+`my_backend_web_package` 必须暴露顶层 `register` 函数。完整配置说明参见通用插件指南中的[通过 pip 分发](/developer-guide/plugins#distribute-via-pip)。
 
 ## 相关页面
 
 - [网页搜索](/user-guide/features/web-search) — 面向用户的功能文档及各后端配置说明
 - [插件概览](/user-guide/features/plugins) — 所有插件类型一览
-- [构建 Hermes 插件](/guides/build-a-hermes-plugin) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
+- [构建 Hermes 插件](/developer-guide/plugins) — 通用工具/hook/斜杠命令指南
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
index 4d2443d23e4..fe6bb448ff6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
@@ -81,7 +81,7 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
 通过自定义工具和可复用技能包扩展 Hermes Agent。
 
 1. [插件](/user-guide/features/plugins)
-2. [构建 Hermes 插件](/guides/build-a-hermes-plugin)
+2. [构建 Hermes 插件](/developer-guide/plugins)
 3. [工具概览](/user-guide/features/tools)
 4. [技能概览](/user-guide/features/skills)
 5. [MCP（模型上下文协议）](/user-guide/features/mcp)
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md
index b842be69d9a..d2e6e8cf7c7 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/github-pr-review-agent.md
@@ -298,6 +298,6 @@ GitHub 对已认证用户每小时允许 5,000 次 API 请求。每次 PR 审查
 
 - **[基于 Webhook 的 PR 审查](./webhook-github-pr-review.md)** — 在 PR 被打开时立即获得审查（需要公开端点）
 - **[每日简报 Bot](/guides/daily-briefing-bot)** — 将 PR 审查与你的晨间资讯摘要结合
-- **[构建 Plugin](/guides/build-a-hermes-plugin)** — 将审查逻辑封装为可共享的 plugin
+- **[构建 Plugin](/developer-guide/plugins)** — 将审查逻辑封装为可共享的 plugin
 - **[Profiles](/user-guide/profiles)** — 运行一个专属审查器 profile，拥有独立的 memory 和配置
 - **[Fallback Providers](/user-guide/features/fallback-providers)** — 确保在某个 provider 不可用时审查任务仍能正常运行
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md
index 6fdc332dedf..788deb3b85b 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/webhook-github-pr-review.md
@@ -325,5 +325,5 @@ platforms:
 
 - **[基于 Cron 的 PR 审查](./github-pr-review-agent.md)** —— 按计划轮询 PR，无需公网端点
 - **[Webhook 参考](/user-guide/messaging/webhooks)** —— webhook 平台的完整配置参考
-- **[构建 Plugin](/guides/build-a-hermes-plugin)** —— 将审查逻辑打包为可共享的 plugin
+- **[构建 Plugin](/developer-guide/plugins)** —— 将审查逻辑打包为可共享的 plugin
 - **[Profiles](/user-guide/profiles)** —— 运行一个拥有独立内存和配置的专属审查者 profile
\ No newline at end of file
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md
index 3a16885b127..a443fab9915 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/work-with-skills.md
@@ -135,7 +135,7 @@ skill_view("writing-plans")
 
 插件 skills **不会**列在系统 prompt 中，也不出现在 `skills_list` 中。它们是按需加载的——当你知道某个插件提供了某个 skill 时，显式加载它。加载后，agent 会看到一个横幅，列出同一插件的其他 skills。
 
-关于如何在自己的插件中捆绑 skills，请参见 [构建 Hermes 插件 → 捆绑 skills](/guides/build-a-hermes-plugin#bundle-skills)。
+关于如何在自己的插件中捆绑 skills，请参见 [构建 Hermes 插件 → 捆绑 skills](/developer-guide/plugins#bundle-skills)。
 
 ---
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md
index 39ca64095d1..3906102e00d 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/integrations/index.md
@@ -93,7 +93,7 @@ Hermes 可作为 gateway（网关）机器人运行于 19+ 个消息平台，均
 ## 插件
 
 - **[插件系统](/user-guide/features/plugins)** — 无需修改核心代码，通过自定义工具、生命周期 hook（钩子）和 CLI 命令扩展 Hermes。插件从 `~/.hermes/plugins/`、项目本地 `.hermes/plugins/` 以及通过 pip 安装的入口点自动发现。
-- **[构建插件](/guides/build-a-hermes-plugin)** — 创建包含工具、hook 和 CLI 命令的 Hermes 插件的分步指南。
+- **[构建插件](/developer-guide/plugins)** — 创建包含工具、hook 和 CLI 命令的 Hermes 插件的分步指南。
 
 ## 训练与评估
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md
index 8c2a8216937..5c6a85144ff 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/cli-commands.md
@@ -1026,7 +1026,7 @@ Provider plugin 选择保存到 `config.yaml`：
 
 通用 plugin 禁用列表存储在 `config.yaml` 的 `plugins.disabled` 下。
 
-参见 [Plugins](../user-guide/features/plugins.md) 和 [构建 Hermes Plugin](../guides/build-a-hermes-plugin.md)。
+参见 [Plugins](../user-guide/features/plugins.md) 和 [构建 Hermes Plugin](../developer-guide/plugins/index.md)。
 
 ## `hermes tools`
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md
index 834b28b6c0a..5ac19fae8f1 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/built-in-plugins.md
@@ -9,7 +9,7 @@ description: "随 Hermes Agent 附带并通过生命周期 hook 自动运行的
 
 Hermes 随仓库附带了一小组插件。它们位于 `<repo>/plugins/<name>/`，与用户安装在 `~/.hermes/plugins/` 中的插件一同自动加载。它们使用与第三方插件相同的插件接口——hook、工具、斜杠命令——只是在仓库内维护。
 
-请参阅 [插件](/user-guide/features/plugins) 页面了解通用插件系统，以及 [构建 Hermes 插件](/guides/build-a-hermes-plugin) 了解如何编写自己的插件。
+请参阅 [插件](/user-guide/features/plugins) 页面了解通用插件系统，以及 [构建 Hermes 插件](/developer-guide/plugins) 了解如何编写自己的插件。
 
 ## 发现机制
 
@@ -253,7 +253,7 @@ agent 会启动会议加入流程，在通话进行时将转录内容流式传
 
 ## 添加内置插件
 
-内置插件的编写方式与其他 Hermes 插件完全相同——参见 [构建 Hermes 插件](/guides/build-a-hermes-plugin)。唯一的区别是：
+内置插件的编写方式与其他 Hermes 插件完全相同——参见 [构建 Hermes 插件](/developer-guide/plugins)。唯一的区别是：
 
 - 目录位于 `<repo>/plugins/<name>/`，而非 `~/.hermes/plugins/<name>/`
 - 在 `hermes plugins list` 中，manifest 来源显示为 `bundled`
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
index c81e84956fb..85265ecfd21 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/hooks.md
@@ -801,7 +801,7 @@ def my_callback(session_id: str, platform: str, **kwargs):
 
 ---
 
-参见 **[构建插件指南](/guides/build-a-hermes-plugin)**，获取包含工具 schema、处理器和高级 hook 模式的完整演练。
+参见 **[构建插件指南](/developer-guide/plugins)**，获取包含工具 schema、处理器和高级 hook 模式的完整演练。
 
 ---
 
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md
index 12a83f2a6d0..7e8aa776b82 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/plugins.md
@@ -12,7 +12,7 @@ Hermes 提供了一套插件系统，可在不修改核心代码的情况下添
 如果你想为自己、团队或某个项目创建自定义工具，这通常是正确的路径。开发者指南中的
 [Adding Tools](/developer-guide/adding-tools) 页面针对的是存放在 `tools/` 和 `toolsets.py` 中的 Hermes 内置核心工具。
 
-**→ [构建 Hermes Plugin](/guides/build-a-hermes-plugin)** — 包含完整可运行示例的分步指南。
+**→ [构建 Hermes Plugin](/developer-guide/plugins)** — 包含完整可运行示例的分步指南。
 
 ## 快速概览
 
@@ -221,9 +221,9 @@ Memory provider 和 context engine 是 **provider 插件** — 每种类型同
 
 | 想要添加… | 方式 | 编写指南 |
 |---|---|---|
-| LLM 可调用的**工具** | Python 插件 — `ctx.register_tool()` | [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Adding Tools](/developer-guide/adding-tools) |
-| **生命周期 hook**（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/guides/build-a-hermes-plugin) |
-| CLI / gateway 的**斜杠命令** | Python 插件 — `ctx.register_command()` | [Build a Hermes Plugin](/guides/build-a-hermes-plugin) · [Extending the CLI](/developer-guide/extending-the-cli) |
+| LLM 可调用的**工具** | Python 插件 — `ctx.register_tool()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Adding Tools](/developer-guide/adding-tools) |
+| **生命周期 hook**（LLM 前后、会话开始/结束、工具过滤） | Python 插件 — `ctx.register_hook()` | [Hooks reference](/user-guide/features/hooks) · [Build a Hermes Plugin](/developer-guide/plugins) |
+| CLI / gateway 的**斜杠命令** | Python 插件 — `ctx.register_command()` | [Build a Hermes Plugin](/developer-guide/plugins) · [Extending the CLI](/developer-guide/extending-the-cli) |
 | `hermes <thing>` 的**子命令** | Python 插件 — `ctx.register_cli_command()` | [Extending the CLI](/developer-guide/extending-the-cli) |
 | 插件附带的**skill** | Python 插件 — `ctx.register_skill()` | [Creating Skills](/developer-guide/creating-skills) |
 | **推理后端**（LLM provider：OpenAI 兼容、Codex、Anthropic-Messages、Bedrock） | Provider 插件 — 在 `plugins/model-providers/<name>/` 中调用 `register_provider(ProviderProfile(...))` | **[Model Provider Plugins](/developer-guide/model-provider-plugin)** · [Adding Providers](/developer-guide/adding-providers) |
@@ -347,4 +347,4 @@ ctx.inject_message("New data arrived from the webhook", role="user")
 `inject_message` 仅在 CLI 模式下可用。在 gateway 模式下，没有 CLI 引用，该方法返回 `False`。
 :::
 
-完整的处理器约定、schema 格式、hook 行为、错误处理和常见错误请参见 **[完整指南](/guides/build-a-hermes-plugin)**。
\ No newline at end of file
+完整的处理器约定、schema 格式、hook 行为、错误处理和常见错误请参见 **[完整指南](/developer-guide/plugins)**。
\ No newline at end of file
diff --git a/website/sidebars.ts b/website/sidebars.ts
index b012354a532..189406e2599 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -37,6 +37,7 @@ const sidebars: SidebarsConfig = {
           items: [
             'user-guide/secrets/index',
             'user-guide/secrets/bitwarden',
+            'user-guide/secrets/onepassword',
           ],
         },
         'user-guide/sessions',
@@ -690,7 +691,6 @@ const sidebars: SidebarsConfig = {
         'guides/use-mcp-with-hermes',
         'guides/use-soul-with-hermes',
         'guides/use-voice-mode-with-hermes',
-        'guides/build-a-hermes-plugin',
         'guides/automate-with-cron',
         'guides/cron-script-only',
         'guides/automation-blueprints',
@@ -736,13 +736,21 @@ const sidebars: SidebarsConfig = {
             'developer-guide/adding-tools',
             'developer-guide/adding-providers',
             'developer-guide/adding-platform-adapters',
-            'developer-guide/memory-provider-plugin',
-            'developer-guide/context-engine-plugin',
-            'developer-guide/model-provider-plugin',
-            'developer-guide/image-gen-provider-plugin',
-            'developer-guide/video-gen-provider-plugin',
-            'developer-guide/web-search-provider-plugin',
-            'developer-guide/plugin-llm-access',
+            {
+              type: 'category',
+              label: 'Plugins',
+              link: {type: 'doc', id: 'developer-guide/plugins/index'},
+              items: [
+                'developer-guide/plugin-llm-access',
+                'developer-guide/memory-provider-plugin',
+                'developer-guide/context-engine-plugin',
+                'developer-guide/secret-source-plugin',
+                'developer-guide/model-provider-plugin',
+                'developer-guide/image-gen-provider-plugin',
+                'developer-guide/video-gen-provider-plugin',
+                'developer-guide/web-search-provider-plugin',
+              ],
+            },
             'developer-guide/creating-skills',
             'developer-guide/extending-the-cli',
           ],