docs: fix and reciprocate cross-page links across install, help, reference, start, and web (#143773)

Closes link-kind audit findings for docs/install/, docs/help/, docs/reference/,
docs/start/, docs/web/ and docs/nodes/.

- start/hubs: point the Model providers hub entry at the provider directory
  (/providers) instead of the /providers/models quickstart duplicate.
- Add the missing reciprocal links the audit found: Cloudflare Containers,
  Kubernetes and Ansible from Docker and the Linux server page; macOS VMs from
  iMessage and the Linux server page; Podman from the sandbox Podman backend;
  Updating from Migrating; Docker from the Configuration page; Backups,
  Bootstrapping and Default AGENTS.md from Agent workspace; Bootstrapping from
  the BOOTSTRAP template; Tests from the two help testing pages; Session
  management deep dive from Context engine; Transcript hygiene from Session and
  Session pruning; SecretRef credential surface from Auth credential semantics;
  Device model database from the Nodes macOS section; RPC adapters from Signal
  and iMessage; Personal assistant setup from Getting started; Onboarding from
  the macOS platform page; The Lobster from Control UI settings; Release
  performance sweep from Dependency locking; Release policy from Release
  channels; Full release validation and Update and plugin tests from RELEASING.
- help/index: list the Scripts page under Testing.
- help/faq-first-run: add the Models FAQ to Related (was one-directional).
- reference/credits: replace the two off-topic Related links with the lore and
  pull-request-review-flow pages.
- reference/rich-output-protocol: replace the unrelated RPC adapters link with
  the Control UI hosted-embeds section that actually renders [embed ...].
- web/lobster: add a Related section.
- glossary: 17 append-only zh-CN sources for the new list-item link labels, each
  inserted beside a related existing term rather than at the end of the array.

docs/.i18n/glossary.zh-CN.json

@@ -51,6 +51,10 @@
     "source": "Secrets management",
     "target": "密钥管理"
   },
+  {
+    "source": "SecretRef credential surface",
+    "target": "SecretRef 凭据覆盖面"
+  },
   {
     "source": "Secrets runtime model",
     "target": "密钥运行时模型"
@@ -243,6 +247,10 @@
     "source": "Gateway protocol",
     "target": "Gateway 协议"
   },
+  {
+    "source": "RPC adapters",
+    "target": "RPC 适配器"
+  },
   {
     "source": "Gateway RPC methods",
     "target": "Gateway RPC 方法"
@@ -483,6 +491,10 @@
     "source": "Getting started",
     "target": "入门指南"
   },
+  {
+    "source": "Personal assistant setup",
+    "target": "个人助理设置"
+  },
   {
     "source": "Quick start",
     "target": "快速开始"
@@ -635,6 +647,10 @@
     "source": "Model providers",
     "target": "模型提供商"
   },
+  {
+    "source": "Models FAQ",
+    "target": "模型常见问题"
+  },
   {
     "source": "Quick rules",
     "target": "快速规则"
@@ -707,6 +723,18 @@
     "source": "VPS hosting",
     "target": "VPS 托管"
   },
+  {
+    "source": "Ansible",
+    "target": "Ansible"
+  },
+  {
+    "source": "Kubernetes",
+    "target": "Kubernetes"
+  },
+  {
+    "source": "Cloudflare Containers",
+    "target": "Cloudflare Containers"
+  },
   {
     "source": "Fly.io",
     "target": "Fly.io"
@@ -723,6 +751,10 @@
     "source": "Linux server",
     "target": "Linux 服务器"
   },
+  {
+    "source": "macOS VMs",
+    "target": "macOS 虚拟机"
+  },
   {
     "source": "Platforms",
     "target": "平台"
@@ -771,6 +803,10 @@
     "source": "Credits",
     "target": "致谢"
   },
+  {
+    "source": "OpenClaw lore",
+    "target": "OpenClaw 传说"
+  },
   {
     "source": "Features",
     "target": "功能"
@@ -1147,6 +1183,10 @@
     "source": "Release policy",
     "target": "发布策略"
   },
+  {
+    "source": "Full release validation",
+    "target": "完整发布验证"
+  },
   {
     "source": "Release notes",
     "target": "发布说明"
@@ -1599,6 +1639,10 @@
     "source": "Migrating",
     "target": "迁移"
   },
+  {
+    "source": "Backups",
+    "target": "备份"
+  },
   {
     "source": "Migrating from Hermes",
     "target": "从 Hermes 迁移"
@@ -1611,6 +1655,14 @@
     "source": "Agent workspace",
     "target": "Agent 工作区"
   },
+  {
+    "source": "Default AGENTS.md",
+    "target": "默认 AGENTS.md"
+  },
+  {
+    "source": "Bootstrapping",
+    "target": "引导初始化"
+  },
   {
     "source": "Migration",
     "target": "迁移"
@@ -1647,6 +1699,14 @@
     "source": "Testing",
     "target": "测试"
   },
+  {
+    "source": "Tests",
+    "target": "测试"
+  },
+  {
+    "source": "Scripts",
+    "target": "脚本"
+  },
   {
     "source": "Update and plugin tests",
     "target": "更新和插件测试"
@@ -1923,6 +1983,10 @@
     "source": "Control UI",
     "target": "Control UI"
   },
+  {
+    "source": "Hosted embeds",
+    "target": "托管嵌入"
+  },
   {
     "source": "Control UI URLs",
     "target": "Control UI 地址"
@@ -2599,6 +2663,10 @@
     "source": "Session management",
     "target": "会话管理"
   },
+  {
+    "source": "Transcript hygiene",
+    "target": "转录净化"
+  },
   {
     "source": "Session tools",
     "target": "会话工具"

docs/auth-credential-semantics.md

@@ -207,3 +207,4 @@ Human-friendly detail and the stable reason code follow on subsequent lines in t
 
 - [Secrets management](/gateway/secrets)
 - [Auth storage](/concepts/oauth)
+- [SecretRef credential surface](/reference/secretref-credential-surface) - which credential fields accept a SecretRef instead of a raw secret value

docs/channels/imessage.md

@@ -122,4 +122,10 @@ Every section heading from the previous single-page version keeps its anchor her
   <Card title="Configuration reference" icon="sliders" href="/gateway/config-channels#imessage">
     Full iMessage field reference.
   </Card>
+  <Card title="RPC adapters" icon="plug" href="/reference/rpc">
+    The line-delimited JSON-RPC stdio protocol OpenClaw speaks to `imsg rpc`.
+  </Card>
+  <Card title="macOS VMs" icon="display" href="/install/macos-vm">
+    Run OpenClaw in a sandboxed macOS VM, local or hosted, when you want iMessage isolated from your main Mac.
+  </Card>
 </CardGroup>

docs/channels/signal.md

@@ -512,4 +512,5 @@ Related global options:
 - [Pairing](/channels/pairing) - DM authentication and pairing flow
 - [Groups](/channels/groups) - group chat behavior and mention gating
 - [Channel Routing](/channels/channel-routing) - session routing for messages
+- [RPC adapters](/reference/rpc) - the signal-cli JSON-RPC-over-HTTP daemon pattern behind this channel
 - [Security](/gateway/security) - access model and hardening

docs/concepts/agent-workspace.md

@@ -238,6 +238,9 @@ Suggested `.gitignore` starter:
 
 ## Related
 
+- [Backups](/install/backups) - archives, per-database snapshots, scheduling, and offsite copies of state and workspace
+- [Bootstrapping](/start/bootstrapping) - the first-run ritual that seeds a new workspace and its identity files
+- [Default AGENTS.md](/reference/AGENTS.default) - the default agent instructions and skills roster placed in the workspace
 - [Heartbeat](/gateway/heartbeat) - heartbeat monitors and cron scratch
 - [Sandboxing](/gateway/sandboxing) - workspace access in sandboxed environments
 - [Session](/concepts/session) - session storage paths

docs/concepts/context-engine.md

@@ -463,3 +463,4 @@ The slot is exclusive at run time - only one registered context engine is resolv
 - [Plugin Architecture](/plugins/architecture) - registering context engine plugins
 - [Plugin manifest](/plugins/manifest) - plugin manifest fields
 - [Plugins](/tools/plugin) - plugin overview
+- [Session management deep dive](/reference/session-management-compaction) - the session store, transcript events, and auto-compaction internals

docs/concepts/session-pruning.md

@@ -155,3 +155,4 @@ They complement each other -- pruning keeps tool output lean between compaction
 - [Session management](/concepts/session)
 - [Session tools](/concepts/session-tool)
 - [Context engine](/concepts/context-engine)
+- [Transcript hygiene](/reference/transcript-hygiene) - in-memory, provider-specific transcript sanitization applied before a run

docs/concepts/session.md

@@ -346,5 +346,6 @@ Preview any maintenance run with `openclaw sessions cleanup --dry-run`.
 
 - [Session pruning](/concepts/session-pruning)
 - [Session tools](/concepts/session-tool)
+- [Transcript hygiene](/reference/transcript-hygiene) - in-memory, provider-specific transcript sanitization applied before a run
 - [Command queue](/concepts/queue)
 - [Multi-agent sandbox and tools](/tools/multi-agent-sandbox-tools) - per-agent sandbox and tool restrictions, including session visibility

docs/gateway/configuration.md

@@ -175,5 +175,6 @@ _Related: [Configuration Examples](/gateway/configuration-examples) · [Configur
 - [Gateway runbook](/gateway)
 - [`openclaw config`](/cli/config) — read and write these settings from the CLI
 - [`openclaw configure`](/cli/configure) — guided editor for these settings
+- [Docker](/install/docker) — container deployment, its environment variables, and the mounted config and state paths
 - [Security audit checks](/gateway/security/audit-checks) — what the audit flags in this configuration
 - [Trusted proxy auth](/gateway/trusted-proxy-auth) — configuring the Gateway behind a reverse proxy

docs/gateway/sandboxing/podman-backend.md

@@ -6,6 +6,8 @@ read_when: "You are using Podman instead of Docker for sandboxed tool execution.
 
 Selecting the native Podman CLI as a built-in backend, the Docker settings it reuses, and its rootless user-mapping rules.
 
+This page covers Podman as the sandbox backend for agent tool execution. Running the Gateway itself in a rootless Podman container is a separate setup: see [Podman](/install/podman).
+
 ## Podman backend
 
 Use `sandbox.backend: "podman"` to select the native `podman` CLI directly. This is a built-in backend, not a plugin. It does not probe or select Docker, even when the `docker` executable is installed.

docs/gateway/security/dependency-locking.md

@@ -68,3 +68,7 @@ tar -tf /tmp/openclaw-plugin-pack/openclaw-discord-<version>.tgz | grep -E '^pac
 ```
 
 The `node_modules` entries prove that the plugin carries its bundled runtime payload. The final check proves that neither npm lockfile format ships in the tarball.
+
+## Related
+
+- [Release performance sweep](/reference/release-performance-sweep) - the May 2026 package-size, dependency, and shrinkwrap audit this policy came out of

docs/help/faq-first-run.md

@@ -85,6 +85,7 @@ still resolves. Each entry points at the page that now holds the content.
 ## Related
 
 - [FAQ](/help/faq) - the main FAQ (models, sessions, gateway, security, more)
+- [Models FAQ](/help/faq-models) - model defaults, selection, aliases, switching, failover, and auth profiles
 - [Install overview](/install)
 - [Getting started](/start/getting-started)
 - [Troubleshooting](/help/troubleshooting)

docs/help/index.md

@@ -31,6 +31,7 @@ Fastest path to unstuck, by symptom:
 - [Testing](/help/testing) - test suites and Docker runners
 - [Update and plugin tests](/help/testing-updates-plugins) - package update, migration, and plugin install validation
 - [Live tests](/help/testing-live) - network-touching provider and CLI smokes
+- [Scripts](/help/scripts) - helper scripts under `scripts/` and when to prefer the CLI
 
 ## Community and meta
 

docs/help/testing-live.md

@@ -90,3 +90,4 @@ entry points at the page that now holds the content.
 ## Related
 
 - [Testing](/help/testing) - unit, integration, QA, and Docker suites
+- [Tests](/reference/test) - index of the testing reference, one page per reader job

docs/help/testing-updates-plugins.md

@@ -459,3 +459,9 @@ Start with the artifact identity:
 
 Prefer rerunning the failed exact lane with the same package artifact over
 rerunning the whole release umbrella.
+
+## Related
+
+- [Tests](/reference/test) - index of the testing reference, one page per reader job
+- [Testing](/help/testing) - the full testing kit: suites, live lanes, and Docker runners
+- [Release policy](/reference/RELEASING) - the release process this checklist gates

docs/install/backups.md

@@ -382,6 +382,7 @@ first with `openclaw database preflight`; see
 
 - [Agent workspace](/concepts/agent-workspace#git-backup-recommended-private) for keeping workspace files in a private git repository
 - [Backup CLI reference](/cli/backup)
+- [Cloudflare Containers](/install/cloudflare) — continuous Litestream replication to R2 for an ephemeral container deployment
 - [Database schemas](/reference/database-schemas)
 - [Migrating between machines](/install/migrating)
 - [Updating](/install/updating)

docs/install/development-channels.md

@@ -199,3 +199,4 @@ Beta and dev builds may **not** include a macOS app release. That is fine:
 
 - [Updating](/install/updating)
 - [Installer internals](/install/installer)
+- [Release policy](/reference/RELEASING) - how releases are cut and published into these channels

docs/install/docker.md

@@ -350,5 +350,8 @@ docker compose exec openclaw-gateway sh -lc 'node dist/index.js gateway health -
 
 - [Install Overview](/install) — all installation methods
 - [Podman](/install/podman) — Podman alternative to Docker
+- [Kubernetes](/install/kubernetes) — a minimal Kustomize starting point for running the Gateway on a cluster
+- [Ansible](/install/ansible) — automated server deployment with Tailscale VPN and firewall isolation
+- [Cloudflare Containers](/install/cloudflare) — experimental Worker plus container deployment with Litestream backups to R2
 - [Updating](/install/updating) — keeping OpenClaw up to date
 - [Configuration](/gateway/configuration) — gateway configuration after install

docs/install/migrating.md

@@ -148,5 +148,6 @@ In-place plugin upgrades preserve the same plugin id and config keys but may mov
 - [`openclaw migrate`](/cli/migrate): CLI reference for cross-system imports.
 - [Install overview](/install): all installation methods.
 - [Doctor](/gateway/doctor): post-migration health check.
+- [Updating](/install/updating): updating an existing install in place, plus rollback strategy.
 - [Uninstall](/install/uninstall): removing OpenClaw cleanly.
 - [`openclaw backup`](/cli/backup) — create the archive this migration restores

docs/nodes/index.md

@@ -18,6 +18,9 @@ adds native widget-panel, camera, screen, notification, and computer-control com
 to the same node-host command surface used by `openclaw node run`. Do not start a
 second CLI node on that Mac; the app runs the matching CLI node-host runtime as
 an internal worker and remains the sole Gateway connection and node identity.
+The app's **Instances** UI shows each device under a friendly hardware name; see
+[Device model database](/reference/device-models) for how Apple model
+identifiers are vendored and mapped.
 
 Nodes are **peripherals**, not gateways: they don't run the gateway service, and channel messages (Telegram, WhatsApp, etc.) land on the gateway, not on nodes.
 

docs/platforms/macos.md

@@ -263,5 +263,6 @@ own docs.
 
 - [Platforms](/platforms)
 - [Getting started](/start/getting-started)
+- [Onboarding](/start/onboarding) - the macOS app's first-run flow: where the Gateway runs, runtime install, and connecting a provider
 - [Gateway](/gateway)
 - [Exec approvals](/tools/exec-approvals)

docs/reference/RELEASING.md

@@ -1204,3 +1204,5 @@ Maintainers use the private release docs in [`openclaw/maintainers/release/READM
 ## Related
 
 - [Release channels](/install/development-channels)
+- [Full release validation](/reference/full-release-validation) - the release product-validation umbrella and its child workflows
+- [Update and plugin tests](/help/testing-updates-plugins) - proving the installable package updates real user state before a release

docs/reference/credits.md

@@ -27,5 +27,5 @@ MIT, copyright OpenClaw Foundation. Third-party notices for incorporated or adap
 
 ## Related
 
-- [Token use and costs](/reference/token-use)
-- [Release policy](/reference/RELEASING)
+- [OpenClaw lore](/start/lore) - the backstory behind the name, the shell, and the space lobster
+- [Pull request review flow](/reference/pull-request-review-flow) - how a contribution moves through Barnacle and ClawSweeper review

docs/reference/rich-output-protocol.md

@@ -101,5 +101,5 @@ The normalized/stored assistant content block is a structured `canvas` item:
 
 ## Related
 
-- [RPC adapters](/reference/rpc)
+- [Hosted embeds](/web/control-ui/chat#hosted-embeds) - how the Control UI renders `[embed ...]` and its iframe sandbox policy
 - [Typebox](/concepts/typebox)

docs/reference/templates/BOOTSTRAP.md

@@ -121,3 +121,4 @@ when a `memory/` folder exists.
 ## Related
 
 - [Agent workspace](/concepts/agent-workspace)
+- [Bootstrapping](/start/bootstrapping) - the first-run ritual this template drives, and when the file is removed

docs/start/getting-started.md

@@ -199,5 +199,6 @@ Full reference: [Environment variables](/help/environment).
 - [Install overview](/install)
 - [Channels overview](/channels)
 - [Setup](/start/setup)
+- [Personal assistant setup](/start/openclaw) - end-to-end guide to a dedicated number that behaves like an always-on assistant
 - [Triage](/cli/triage)
 - [Troubleshooting](/help/troubleshooting)

docs/start/hubs.md

@@ -68,7 +68,7 @@ Use these hubs to discover more of the documentation, including deep dives and r
 ## Providers + ingress
 
 - [Chat channels hub](/channels)
-- [Model providers hub](/providers/models)
+- [Model providers hub](/providers)
 - [Discord](/channels/discord)
 - [iMessage](/channels/imessage)
 - [Mattermost](/channels/mattermost)

docs/vps.md

@@ -136,3 +136,6 @@ diagnostics, see [Linux memory pressure and OOM kills](/platforms/linux#memory-p
 - [DigitalOcean](/install/digitalocean)
 - [Fly.io](/install/fly)
 - [Hetzner](/install/hetzner)
+- [Ansible](/install/ansible) — automated deployment to remote Debian/Ubuntu servers with Tailscale VPN and firewall isolation
+- [Kubernetes](/install/kubernetes) — a minimal Kustomize starting point when you run the Gateway on a cluster instead of a single VPS
+- [macOS VMs](/install/macos-vm) — a sandboxed macOS VM when you need macOS itself (iMessage) rather than a Linux host

docs/web/control-ui/settings.md

@@ -97,6 +97,8 @@ The **Typography** block lets you choose an **Interface** face and a separate **
 
 Appearance also has a Text size setting. It applies to chat text, composer text, tool cards, and chat sidebars, and keeps text inputs at least 16px so mobile Safari does not auto-zoom on focus.
 
+Appearance also carries the **Lobster visits** and **Lobster sounds** toggles and the Lobsterdex. Both toggles are browser-local. See [The Lobster](/web/lobster) for what the sidebar visitor does and how to turn it off for good.
+
 When your connection is bound to an authenticated Gateway profile, theme, theme mode, and accent color are saved to that profile instead of the gateway config. They follow you across devices without changing anyone else's appearance, override gateway-wide `ui.prefs` values, and update your connected clients live. Connections without an authenticated profile continue syncing these preferences through the gateway config exactly as before. Language and chat display preferences remain gateway-config preferences for every connection. Each browser keeps a local mirror for instant boot, and text size remains browser-local. An explicitly read-only connection applies preference changes only in that browser. Changes made while offline remain queued until a later connection can write their applicable preferences; on a read-only reconnect, they continue to behave as browser-local preferences. See [Configuration reference](/gateway/configuration-reference#ui).
 
 ## Manage plugins

docs/web/lobster.md

@@ -80,3 +80,9 @@ Collected observations from people who spend too much time watching their sideba
 ## Privacy
 
 Everything on this page happens locally in your browser: the randomness, the schedule, the Lobsterdex. No lobster data leaves your machine. OpenClaw does not know which lobsters you have met, and frankly it is jealous.
+
+## Related
+
+- [Control UI](/web/control-ui) - the dashboard the lobster wanders into
+- [Settings](/web/control-ui/settings#appearance-themes) - the Control UI Appearance panel that holds the visits and sounds toggles
+- [OpenClaw lore](/start/lore) - why there is a lobster at all