docs(xurl): clarify Docker auth HOME

skills/social-media/xurl/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: xurl
 description: "X/Twitter via xurl CLI: post, search, DM, media, v2 API."
-version: 1.1.1
+version: 1.1.2
 author: xdevplatform + openclaw + Hermes Agent
 license: MIT
 platforms: [linux, macos]
@@ -48,6 +48,8 @@ Forbidden flags in agent commands (they accept inline secrets):
 
 App credential registration and credential rotation must be done by the user manually, outside the agent session. After credentials are registered, the user authenticates with `xurl auth oauth2` — also outside the agent session. Tokens persist to `~/.xurl` in YAML. Each app has isolated tokens. OAuth 2.0 tokens auto-refresh.
 
+When Hermes itself runs in Docker, remember that `~/.xurl` means the HOME of the process running `xurl`. Hermes tool subprocesses use `$HERMES_HOME/home` as HOME, so in the official Docker image (`HERMES_HOME=/opt/data`) agent-run `xurl` commands read credentials from `/opt/data/home/.xurl`, not `/opt/data/.xurl`. Run manual auth with `HOME=/opt/data/home` so the OAuth files land where Hermes will look.
+
 ---
 
 ## Installation
@@ -83,6 +85,16 @@ If `xurl` is installed but `auth status` shows no apps or tokens, the user needs
 
 These steps must be performed by the user directly, NOT by the agent, because they involve pasting secrets. Direct the user to this block; do not execute it for them.
 
+:::tip Dockerized Hermes
+If Hermes is running inside the official Docker image with `/opt/data` mounted as the data directory, run the setup commands with the same HOME Hermes tool subprocesses use:
+
+```bash
+export HOME=/opt/data/home
+```
+
+This stores xurl credentials in `/opt/data/home/.xurl`. If you instead authenticate with `HOME=/opt/data`, the OAuth flow can succeed but Hermes-run `xurl` commands will still report no apps or tokens because they read `$HERMES_HOME/home/.xurl`.
+:::
+
 1. Create or open an app at https://developer.x.com/en/portal/dashboard
 2. Set the redirect URI to `http://localhost:8080/callback`
 3. Copy the app's Client ID and Client Secret

website/docs/user-guide/docker.md

@@ -125,6 +125,21 @@ The `/opt/data` volume is the single source of truth for all Hermes state. It ma
 Never run two Hermes **gateway** containers against the same data directory simultaneously — session files and memory stores are not designed for concurrent write access.
 :::
 
+### Tool auth files and subprocess HOME
+
+Some CLI tools store OAuth state below `~`, not directly in `/opt/data`. Hermes tool subprocesses run with `HOME=$HERMES_HOME/home`; in this Docker layout that resolves to `/opt/data/home`. When a tool's docs mention `~/.tool-name`, create or verify that state under `/opt/data/home`, not `/opt/data`.
+
+For example, the bundled [`xurl` skill](./skills/bundled/social-media/social-media-xurl.md) stores X/Twitter OAuth state in `~/.xurl`. Inside the official Hermes container, run manual xurl setup yourself, outside an agent session, with:
+
+```sh
+HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
+HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME
+HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME
+HOME=/opt/data/home xurl auth status
+```
+
+Replace the placeholders in your own shell; do not paste client IDs, client secrets, or tokens into chat. If those commands are run with `HOME=/opt/data`, the OAuth flow can succeed but Hermes-run `xurl` commands will look in `/opt/data/home/.xurl` and report no apps or tokens.
+
 ## Multi-profile support
 
 Hermes supports [multiple profiles](../reference/profile-commands.md) — separate `~/.hermes/` directories that let you run independent agents (different SOUL, skills, memory, sessions, credentials) from a single installation. **When running under Docker, using Hermes' built-in multi-profile feature is not recommended.**

website/docs/user-guide/skills/bundled/social-media/social-media-xurl.md

@@ -16,7 +16,7 @@ X/Twitter via xurl CLI: post, search, DM, media, v2 API.
 |---|---|
 | Source | Bundled (installed by default) |
 | Path | `skills/social-media/xurl` |
-| Version | `1.1.1` |
+| Version | `1.1.2` |
 | Author | xdevplatform + openclaw + Hermes Agent |
 | License | MIT |
 | Platforms | linux, macos |
@@ -62,6 +62,8 @@ Forbidden flags in agent commands (they accept inline secrets):
 
 App credential registration and credential rotation must be done by the user manually, outside the agent session. After credentials are registered, the user authenticates with `xurl auth oauth2` — also outside the agent session. Tokens persist to `~/.xurl` in YAML. Each app has isolated tokens. OAuth 2.0 tokens auto-refresh.
 
+When Hermes itself runs in Docker, remember that `~/.xurl` means the HOME of the process running `xurl`. Hermes tool subprocesses use `$HERMES_HOME/home` as HOME, so in the official Docker image (`HERMES_HOME=/opt/data`) agent-run `xurl` commands read credentials from `/opt/data/home/.xurl`, not `/opt/data/.xurl`. Run manual auth with `HOME=/opt/data/home` so the OAuth files land where Hermes will look.
+
 ---
 
 ## Installation
@@ -97,6 +99,16 @@ If `xurl` is installed but `auth status` shows no apps or tokens, the user needs
 
 These steps must be performed by the user directly, NOT by the agent, because they involve pasting secrets. Direct the user to this block; do not execute it for them.
 
+:::tip Dockerized Hermes
+If Hermes is running inside the official Docker image with `/opt/data` mounted as the data directory, run the setup commands with the same HOME Hermes tool subprocesses use:
+
+```bash
+export HOME=/opt/data/home
+```
+
+This stores xurl credentials in `/opt/data/home/.xurl`. If you instead authenticate with `HOME=/opt/data`, the OAuth flow can succeed but Hermes-run `xurl` commands will still report no apps or tokens because they read `$HERMES_HOME/home/.xurl`.
+:::
+
 1. Create or open an app at https://developer.x.com/en/portal/dashboard
 2. Set the redirect URI to `http://localhost:8080/callback`
 3. Copy the app's Client ID and Client Secret