diff --git a/docs/automation/hooks.md b/docs/automation/hooks.md
index deda79d3db5..a470bef8540 100644
--- a/docs/automation/hooks.md
+++ b/docs/automation/hooks.md
@@ -17,7 +17,7 @@ Hooks are small scripts that run when something happens. There are two kinds:
 - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
 - **Webhooks**: external HTTP webhooks that let other systems trigger work in OpenClaw. See [Webhook Hooks](/automation/webhook) or use `openclaw webhooks` for Gmail helper commands.
 
-Hooks can also be bundled inside plugins; see [Plugins](/tools/plugin#plugin-hooks).
+Hooks can also be bundled inside plugins; see [Plugin hooks](/plugins/architecture#provider-runtime-hooks).
 
 Common uses:
 
diff --git a/docs/cli/hooks.md b/docs/cli/hooks.md
index 8aaaa6fd63d..939dac99c66 100644
--- a/docs/cli/hooks.md
+++ b/docs/cli/hooks.md
@@ -13,7 +13,7 @@ Manage agent hooks (event-driven automations for commands like `/new`, `/reset`,
 Related:
 
 - Hooks: [Hooks](/automation/hooks)
-- Plugin hooks: [Plugins](/tools/plugin#plugin-hooks)
+- Plugin hooks: [Plugin hooks](/plugins/architecture#provider-runtime-hooks)
 
 ## List All Hooks
 
diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md
index 6d0fa0af76b..47ef4930b8a 100644
--- a/docs/cli/plugins.md
+++ b/docs/cli/plugins.md
@@ -168,7 +168,7 @@ Each plugin is classified by what it actually registers at runtime:
 - **hook-only** — only hooks, no capabilities or surfaces
 - **non-capability** — tools/commands/services but no capabilities
 
-See [Plugins](/tools/plugin#plugin-shapes) for more on the capability model.
+See [Plugin shapes](/plugins/architecture#plugin-shapes) for more on the capability model.
 
 The `--json` flag outputs a machine-readable report suitable for scripting and
 auditing.
diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md
index 32c4c149b20..bf60b23f1d7 100644
--- a/docs/concepts/agent-loop.md
+++ b/docs/concepts/agent-loop.md
@@ -92,7 +92,7 @@ These run inside the agent loop or gateway pipeline:
 - **`session_start` / `session_end`**: session lifecycle boundaries.
 - **`gateway_start` / `gateway_stop`**: gateway lifecycle events.
 
-See [Plugins](/tools/plugin#plugin-hooks) for the hook API and registration details.
+See [Plugin hooks](/plugins/architecture#provider-runtime-hooks) for the hook API and registration details.
 
 ## Streaming + partial replies
 
diff --git a/docs/concepts/model-providers.md b/docs/concepts/model-providers.md
index f5a73d7256e..98f68bef5cc 100644
--- a/docs/concepts/model-providers.md
+++ b/docs/concepts/model-providers.md
@@ -34,7 +34,7 @@ For model selection rules, see [/concepts/models](/concepts/models).
   `fetchUsageSnapshot`.
 - Note: provider runtime `capabilities` is shared runner metadata (provider
   family, transcript/tooling quirks, transport/cache hints). It is not the
-  same as the [public capability model](/tools/plugin#public-capability-model)
+  same as the [public capability model](/plugins/architecture#public-capability-model)
   which describes what a plugin registers (text inference, speech, etc.).
 
 ## Plugin-owned provider behavior
diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md
index 63cfacbee50..42991a83c48 100644
--- a/docs/help/troubleshooting.md
+++ b/docs/help/troubleshooting.md
@@ -63,7 +63,7 @@ Example:
 }
 ```
 
-Reference: [/tools/plugin#distribution-npm](/tools/plugin#distribution-npm)
+Reference: [Plugin architecture](/plugins/architecture)
 
 ## Decision tree
 
diff --git a/docs/plugins/architecture.md b/docs/plugins/architecture.md
index 8134f598424..be0fc317128 100644
--- a/docs/plugins/architecture.md
+++ b/docs/plugins/architecture.md
@@ -684,7 +684,10 @@ api.registerProvider({
   live-model policy.
 - OpenRouter uses `catalog` plus `resolveDynamicModel` and
   `prepareDynamicModel` because the provider is pass-through and may expose new
-  model ids before OpenClaw's static catalog updates.
+  model ids before OpenClaw's static catalog updates; it also uses
+  `capabilities`, `wrapStreamFn`, and `isCacheTtlEligible` to keep
+  provider-specific request headers, routing metadata, reasoning patches, and
+  prompt-cache policy out of core.
 - GitHub Copilot uses `catalog`, `auth`, `resolveDynamicModel`, and
   `capabilities` plus `prepareRuntimeAuth` and `fetchUsageSnapshot` because it
   needs provider-owned device login, model fallback behavior, Claude transcript
@@ -701,9 +704,6 @@ api.registerProvider({
   modern-model matching; Gemini CLI OAuth also uses `formatApiKey`,
   `resolveUsageAuth`, and `fetchUsageSnapshot` for token formatting, token
   parsing, and quota endpoint wiring.
-- OpenRouter uses `capabilities`, `wrapStreamFn`, and `isCacheTtlEligible`
-  to keep provider-specific request headers, routing metadata, reasoning
-  patches, and prompt-cache policy out of core.
 - Moonshot uses `catalog` plus `wrapStreamFn` because it still uses the shared
   OpenAI transport but needs provider-owned thinking payload normalization.
 - Kilocode uses `catalog`, `capabilities`, `wrapStreamFn`, and
diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md
index e7d31e53e57..511c2226b2a 100644
--- a/docs/plugins/manifest.md
+++ b/docs/plugins/manifest.md
@@ -33,7 +33,7 @@ plugin errors and block config validation.
 
 See the full plugin system guide: [Plugins](/tools/plugin).
 For the native capability model and current external-compatibility guidance:
-[Capability model](/tools/plugin#public-capability-model).
+[Capability model](/plugins/architecture#public-capability-model).
 
 ## Required fields
 
@@ -135,7 +135,7 @@ See [Configuration reference](/configuration) for the full `plugins.*` schema.
   `--auth-choice` resolution, preferred-provider mapping, and simple onboarding
   CLI flag registration before provider runtime loads. For runtime wizard
   metadata that requires provider code, see
-  [Provider runtime hooks](/tools/plugin#provider-runtime-hooks).
+  [Provider runtime hooks](/plugins/architecture#provider-runtime-hooks).
 - Exclusive plugin kinds are selected through `plugins.slots.*`.
   - `kind: "memory"` is selected by `plugins.slots.memory`.
   - `kind: "context-engine"` is selected by `plugins.slots.contextEngine`