better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/profiles.md

@@ -0,0 +1,418 @@
+---
+sidebar_position: 2
+---
+
+# Profiles: Running Multiple Agents
+
+Run multiple independent Hermes agents on the same machine — each with its own config, API keys, memory, sessions, skills, and gateway state.
+
+## What are profiles?
+
+A profile is a separate Hermes home directory. Each profile gets its own directory containing its own `config.yaml`, `.env`, `SOUL.md`, memories, sessions, skills, cron jobs, and state database. Profiles let you run separate agents for different purposes — a coding assistant, a personal bot, a research agent — without mixing up Hermes state.
+
+:::caution Give every agent its own profile
+Never point two agent processes at the same profile (the same Hermes home). Both write memory automatically, and each loads the other's writes into its system prompt at session start — so two writers on one home compound each other's state until it stops being anything you configured. Profiles exist exactly to prevent this; agents that need shared memory should use an [external memory provider](/user-guide/features/memory-providers) instead.
+:::
+
+When you create a profile, it automatically becomes its own command. Create a profile called `coder` and you immediately have `coder chat`, `coder setup`, `coder gateway start`, etc.
+
+## Quick start
+
+```bash
+hermes profile create coder       # creates profile + "coder" command alias
+coder setup                       # configure API keys and model
+coder chat                        # start chatting
+```
+
+That's it. `coder` is now its own Hermes profile with its own config, memory, and state.
+
+## Creating a profile
+
+:::tip
+Quickest setup: run `hermes setup --portal` inside the new profile to wire up models + tools at once. See [Nous Portal](/integrations/nous-portal).
+:::
+
+### Blank profile
+
+```bash
+hermes profile create mybot
+```
+
+Creates a fresh profile with bundled skills seeded. Run `mybot setup` to configure API keys, model, and gateway tokens.
+
+If you plan to use this profile as a kanban worker (or want the kanban orchestrator to route work to it), pass `--description "<role>"` at create time so the orchestrator knows what it's good at:
+
+```bash
+hermes profile create researcher --description "Reads source code and external docs, writes findings."
+```
+
+You can also set or auto-generate the description later with `hermes profile describe` — see the [Kanban guide](./features/kanban#auto-vs-manual-orchestration) for the full routing model.
+
+### Clone config only (`--clone`)
+
+```bash
+hermes profile create work --clone
+```
+
+Copies your current profile's `config.yaml`, `.env`, `SOUL.md`, skills, and the curated memory files `memories/MEMORY.md` and `memories/USER.md` into the new profile — memory is treated as part of the agent's identity, like `SOUL.md`. Sessions, `state.db`, cron jobs and everything else start empty. For a blank memory as well, create the profile without `--clone` or delete the two files afterwards; the agent never falls back to another profile's memory when they are absent. Edit `~/.hermes/profiles/work/.env` for different API keys, or `~/.hermes/profiles/work/SOUL.md` for a different personality.
+
+#### Keep a clone's imported agent setups synced (`--sync-imports`)
+
+If the source profile has run [`hermes import-agent`](./import-from-other-agents.md), its `import-sync.json` records which external Claude Code / Codex trees it imported. `--clone` leaves that manifest behind, so the clone gets a one-off copy of those skills and memories and stops there. Add `--sync-imports` to carry the manifest over:
+
+```bash
+hermes profile create work --clone --sync-imports
+hermes -p work import-agent --sync        # pulls changes from the same ~/.claude / ~/.codex
+```
+
+This is explicit, opt-in and one-directional, and it links the clone to the **external agent trees only** — never to the source profile. Both profiles stay independent islands: editing the source's `config.yaml`, `SOUL.md` or skills afterwards never reaches the clone. `--clone-all` copies the manifest as part of the full copy.
+
+### Clone everything (`--clone-all`)
+
+```bash
+hermes profile create backup --clone-all
+```
+
+Copies **everything** — config, API keys, personality, all memories, skills, plugins. A complete working snapshot. Per-profile history is excluded (session history, `state.db`, `backups/`, `state-snapshots/`, `checkpoints/`) — these belong to the source profile and can reach tens of GB. When cloning from the default profile, the local-model runtime trees (`models/`, `runtimes/`, `node/` — downloaded weights and managed binaries, re-fetched on demand) are skipped too, as `hermes backup` already does. **Cron jobs are not cloned** either: they are scheduled work bound to the source profile and its delivery channel, and a clone that inherited them would run every job twice (two gateways, same job ids). The new profile starts with an empty `cron/`. For a full backup including history and cron jobs, use `hermes profile export` or `hermes backup` instead.
+
+:::note OAuth logins are shared, not copied
+Anthropic (Claude Pro/Max), OpenAI Codex, and xAI OAuth logins use **single-use refresh tokens** — a copy of one is not a second credential, it is the same credential with two owners, and the first profile to refresh it revokes it for every other copy. `--clone-all` (and the dashboard's credential mirroring) therefore drops those OAuth rows from the clone. The new profile keeps reading the login from the root `~/.hermes/auth.json`, and a token refresh performed inside any profile is written back to root, so all profiles stay signed in. Static API keys are copied as usual. To give a profile its own separate OAuth login, run `hermes -p <name> auth add <provider>` inside it.
+:::
+
+### Clone from a specific profile
+
+```bash
+hermes profile create work --clone-from coder
+```
+
+`--clone-from <source>` selects the source profile directly and implies a config/skills/SOUL clone. Combine it with `--clone-all` when you want a full copy of that source profile:
+
+```bash
+hermes profile create work-backup --clone-from coder --clone-all
+```
+
+### Messaging channels are never cloned (`--clone-channels` to opt in)
+
+Every clone — `--clone`, `--clone-from`, `--clone-all`, and the dashboard / Desktop / TUI
+"clone from profile" option — copies the source **without its messaging channels**: bot tokens
+and allowlists (`TELEGRAM_BOT_TOKEN`, `DISCORD_ALLOWED_USERS`, `WHATSAPP_ENABLED`,
+`API_SERVER_KEY`, `WEBHOOK_SECRET`, …), the `platforms:` / `telegram:` / `discord:` sections of
+`config.yaml`, `gateway.multiplex_profiles` / `profile_routes`, and (for `--clone-all`) the
+pairing store, WhatsApp session and other per-bot state. Provider and tool API keys, the model
+block, memory settings, skills and `SOUL.md` are copied as before. The command prints which
+platforms were left behind.
+
+The reason is that a bot can only belong to one profile: two standalone gateways holding the
+same token fight over its long-poll, and a [multiplexed gateway](./multi-profile-gateways.md)
+parks the duplicate adapter (and `hermes gateway migrate --multiplex` refuses with one
+duplicate-credential blocker per platform). Configure the new profile's own bots with
+`hermes -p <name> setup` or the dashboard Messaging page.
+
+```bash
+hermes profile create twin --clone --clone-channels   # keep the source's bots anyway
+```
+
+`--clone-channels` is refused when a running multiplexed gateway already serves the source
+(the copy would be parked immediately) — from the CLI, the dashboard and the TUI alike — and
+otherwise prints a warning naming the platforms now shared with the source. It is an error
+without a clone flag. `hermes profile list` prints the same warning for any existing
+profile whose bot credential is byte-identical to the default's, so older clones surface
+before they bite.
+
+**What counts as a channel setting** — the inventory is ownership-based and is judged in the
+*source* profile's plugin scope (its private `plugins/` adapters included):
+
+- every key an adapter declares (tokens, app/client ids, allowlists, allow-all switches, home
+  channels) and every key under its `<PLATFORM>_` prefix, including historical aliases
+  (`WECOM_*`, `SMS_*`/`TWILIO_*`, `QQ_*`, `HASS_*`, `EMAIL_*`);
+- gateway-wide channel policy `GATEWAY_ALLOW_ALL_USERS` / `GATEWAY_ALLOWED_USERS` and the
+  relay enrollment identity `GATEWAY_RELAY_ID` / `GATEWAY_RELAY_SECRET` / `GATEWAY_RELAY_DELIVERY_KEY`;
+- for `--clone-all`, per-bot state files **and directories** (`platforms/`, pairing ledgers,
+  `google_chat_user_tokens/`, `<platform>_*`).
+
+Credentials that a messaging adapter shares with a non-channel capability — `HASS_TOKEN`/`HASS_URL`
+(also the Home Assistant tool), `TWILIO_*` (also the telephony skill), `EMAIL_*` (also
+mail-sending scripts) — are stripped **only when the source's gateway would run that adapter**
+(the platform is enabled in its `config.yaml`, or its credential set is complete and not
+explicitly disabled). A source with `platforms.homeassistant.enabled: false` uses `HASS_TOKEN`
+as a tool key, so the clone keeps it. Allowlists and ports under those prefixes are always
+channel-only and always stripped.
+
+Clones are built in a hidden staging directory beside `profiles/` and published with one
+rename after the strip, so a running multiplexer (which rescans `profiles/` on create) can
+never start adapters on a half-copied tree. A symlinked source `.env`/`config.yaml` is
+materialized as a private copy first — the clone never writes through to the source.
+
+:::tip Honcho memory + profiles
+When Honcho is enabled, clone operations automatically create a dedicated AI peer for the new profile while sharing the same user workspace. Each profile builds its own observations and identity. See [Honcho -- Multi-agent / Profiles](./features/memory-providers.md#honcho) for details.
+:::
+
+## Using profiles
+
+### Command aliases
+
+Every profile automatically gets a command alias at `~/.local/bin/<name>`:
+
+```bash
+coder chat                    # chat with the coder agent
+coder setup                   # configure coder's settings
+coder gateway start           # start coder's gateway
+coder doctor                  # check coder's health
+coder skills list             # list coder's skills
+coder config set model.default anthropic/claude-sonnet-4
+```
+
+The alias works with every hermes subcommand — it's just `hermes -p <name>` under the hood.
+
+### The `-p` flag
+
+You can also target a profile explicitly with any command:
+
+```bash
+hermes -p coder chat
+hermes --profile=coder doctor
+hermes chat -p coder -q "hello"    # works in any position
+```
+
+### Sticky default (`hermes profile use`)
+
+```bash
+hermes profile use coder
+hermes chat                   # now targets coder
+hermes tools                  # configures coder's tools
+hermes profile use default    # switch back
+```
+
+Sets a default so plain `hermes` commands target that profile. Like `kubectl config use-context`.
+
+### Knowing where you are
+
+The CLI always shows which profile is active:
+
+- **Prompt**: `coder ❯` instead of `❯`
+- **Banner**: Shows `Profile: coder` on startup
+- **`hermes profile`**: Shows current profile name, path, model, gateway status
+
+## Profiles vs workspaces vs sandboxing
+
+Profiles are often confused with workspaces or sandboxes, but they are different things:
+
+- A **profile** gives Hermes its own state directory: `config.yaml`, `.env`, `SOUL.md`, sessions, memory, logs, cron jobs, and gateway state.
+- A **workspace** or **working directory** is where terminal commands start. That is controlled separately by `terminal.cwd`.
+- A **sandbox** is what limits filesystem access. Profiles do **not** sandbox the agent.
+
+On the default `local` terminal backend, the agent still has the same filesystem access as your user account. A profile does not stop it from accessing folders outside the profile directory.
+
+If you want a profile to start in a specific project folder, set an explicit absolute `terminal.cwd` in that profile's `config.yaml`:
+
+```yaml
+terminal:
+  backend: local
+  cwd: /absolute/path/to/project
+```
+
+Using `cwd: "."` on the local backend means "the directory Hermes was launched from", not "the profile directory".
+
+Also note:
+
+- `SOUL.md` can guide the model, but it does not enforce a workspace boundary.
+- Changes to `SOUL.md` take effect cleanly on a new session. Existing sessions may still be using the old prompt state.
+- Asking the model "what directory are you in?" is not a reliable isolation test. If you need a predictable starting directory for tools, set `terminal.cwd` explicitly.
+
+## Running gateways
+
+Each profile runs its own gateway as a separate process with its own bot token:
+
+```bash
+coder gateway start           # starts coder's gateway
+assistant gateway start       # starts assistant's gateway (separate process)
+```
+
+### Different bot tokens
+
+Each profile has its own `.env` file. Configure a different Telegram/Discord/Slack bot token in each:
+
+```bash
+# Edit coder's tokens
+nano ~/.hermes/profiles/coder/.env
+
+# Edit assistant's tokens
+nano ~/.hermes/profiles/assistant/.env
+```
+
+### Safety: token locks
+
+If two profiles accidentally use the same bot token, the second gateway will be blocked with a clear error naming the conflicting profile. Supported for Telegram, Discord, Slack, WhatsApp, and Signal.
+
+### Persistent services
+
+```bash
+coder gateway install         # creates hermes-gateway-coder systemd/launchd service
+assistant gateway install     # creates hermes-gateway-assistant service
+```
+
+Each profile gets its own service name. They run independently.
+
+:::note Inside the official Docker image
+Per-profile gateways are supervised by [s6-overlay](https://github.com/just-containers/s6-overlay) (PID 1 in the container), so `hermes profile create <name>` automatically registers an s6 service slot at `/run/service/gateway-<name>/`. `hermes -p <name> gateway start/stop/restart` dispatches to `s6-svc` instead of spawning a bare process — crashes are auto-restarted and `docker restart` preserves the previously-running set of gateways. See [Per-profile gateway supervision](/user-guide/docker#per-profile-gateway-supervision) for details.
+:::
+
+## Configuring profiles
+
+Each profile has its own:
+
+- **`config.yaml`** — model, provider, toolsets, all settings
+- **`.env`** — API keys, bot tokens
+- **`SOUL.md`** — personality and instructions
+
+```bash
+coder config set model.default anthropic/claude-sonnet-4
+echo "You are a focused coding assistant." > ~/.hermes/profiles/coder/SOUL.md
+```
+
+If you want this profile to work in a specific project by default, also set its own `terminal.cwd`:
+
+```bash
+coder config set terminal.cwd /absolute/path/to/project
+```
+
+### From the dashboard
+
+The [web dashboard](features/web-dashboard.md#managing-multiple-profiles)
+is a machine-level surface that can manage **any** profile's config, API
+keys, skills, MCPs, and model via the profile switcher in its sidebar — no
+per-profile dashboard needed. `coder dashboard` routes to the machine
+dashboard with the `coder` profile preselected. The dashboard's Chat tab
+also follows the switcher, spawning a conversation under the selected
+profile's home.
+
+Note: "Set as active" on the dashboard's Profiles page is the sticky
+default for **future CLI/gateway runs** (same as `hermes profile use`) —
+to edit a profile from the dashboard, use the switcher instead.
+
+## Updating
+
+`hermes update` pulls code once (shared) and syncs new bundled skills to **all** profiles automatically:
+
+```bash
+hermes update
+# → Code updated (12 commits)
+# → Skills synced: default (up to date), coder (+2 new), assistant (+2 new)
+```
+
+User-modified skills are never overwritten.
+
+## Managing profiles
+
+```bash
+hermes profile list           # show all profiles with status
+hermes profile show coder     # detailed info for one profile
+hermes profile rename coder dev-bot   # rename (updates alias + service)
+hermes profile migrate-identity coder dev-bot   # retry a rename's identity migration
+hermes profile export coder   # pack into coder.tar.gz (shareable; keys stripped)
+hermes profile import coder.tar.gz   # install an archive as a new profile
+```
+
+In chat, the same two live as `/export` and `/import` — and in the desktop app as **⌘K → Export/Import profile…**. See [Sharing a profile](#sharing-a-profile).
+
+### Naming the default profile
+
+The default profile's internal ID is always `default` — it can't be truly
+renamed because `~/.hermes` is the installation root. Renaming it instead
+sets a **display name**, which UI surfaces show in place of the bare ID:
+
+```bash
+hermes profile rename default Harumesu   # Unicode fine: 小助手
+```
+
+The display name appears in `hermes profile list`/`show`, the `/profile`
+chat command, the dashboard, and the desktop app (including the Bot Mode
+roster). It is presentation-only: `-p default`, service names, cron jobs,
+and every other reference keep using the canonical `default` ID. It is
+stored as `display_name` in `~/.hermes/profile.yaml`; remove that line to
+revert. Named profiles can carry a `display_name` too (it survives a real
+rename), but `rename` for them still renames the profile itself.
+
+## Deleting a profile
+
+```bash
+hermes profile delete coder
+```
+
+This stops the gateway, removes the systemd/launchd service, removes the command alias, and deletes all profile data. You'll be asked to type the profile name to confirm.
+
+Use `--yes` to skip confirmation: `hermes profile delete coder --yes`
+
+:::note
+You cannot delete the default profile (`~/.hermes`). To remove everything, use `hermes uninstall`.
+:::
+
+## Tab completion
+
+```bash
+# Bash
+eval "$(hermes completion bash)"
+
+# Zsh
+eval "$(hermes completion zsh)"
+```
+
+Add the line to your `~/.bashrc` or `~/.zshrc` for persistent completion. Completes profile names after `-p`, profile subcommands, and top-level commands.
+
+## How it works
+
+Profiles use the `HERMES_HOME` environment variable. When you run `coder chat`, the wrapper script sets `HERMES_HOME=~/.hermes/profiles/coder` before launching hermes. Since 119+ files in the codebase resolve paths via `get_hermes_home()`, Hermes state automatically scopes to the profile's directory — config, sessions, memory, skills, state database, gateway PID, logs, and cron jobs.
+
+This is separate from terminal working directory. Tool execution starts from `terminal.cwd` (or the launch directory when `cwd: "."` on the local backend), not automatically from `HERMES_HOME`.
+
+On host installs, tool subprocesses keep your real OS-user `HOME` by default so
+existing CLI credentials under `~` keep working across profiles. Profile data is
+isolated by `HERMES_HOME`, not by changing `HOME`. Container backends still use
+`{HERMES_HOME}/home` for persistent tool state, and host users who need strict
+per-profile tool config can opt in with `terminal.home_mode: profile`.
+
+This means two things that are easy to mix up:
+
+- `HERMES_HOME` is the profile boundary. It controls Hermes config, `.env`,
+  memory, sessions, skills, logs, cron jobs, gateway state, and other Hermes
+  data.
+- `HOME` is the operating-system/user home that external CLIs expect. On host
+  installs, Hermes keeps it as the real user home by default so tools like
+  `git`, `ssh`, `gh`, `az`, `npm`, Claude Code, and Codex find the same
+  credentials they use in your normal shell.
+
+The tradeoff is that host profiles share normal user-level CLI state by default.
+If you need separate CLI identities per profile, set `terminal.home_mode:
+profile` in that profile's `config.yaml`. In that mode Hermes launches tool
+subprocesses with `HOME={HERMES_HOME}/home`; you then need to initialize or link
+the profile-specific `~/.ssh`, `~/.gitconfig`, `~/.config/gh`, cloud CLI auth,
+Claude/Codex auth, npm state, and similar files inside that profile home.
+
+Hermes also exposes `HERMES_REAL_HOME` to subprocesses so scripts can still find
+the actual account home when `home_mode: profile` is active.
+
+The default profile is simply `~/.hermes` itself. No migration needed — existing installs work identically.
+
+## Sharing a profile
+
+A profile you built on one machine can go to another — your own workstation, a teammate's laptop, or the community. Two paths:
+
+**Send a file.** `/export` packs the profile into one `.tar.gz` — skills, memory, persona, crons, plugins, settings, and (from the desktop) your theme and layout. API keys are stripped. The recipient runs `/import`.
+
+```bash
+# In chat, run /export, hand over the file, and they run /import on it
+hermes profile export coder
+hermes profile import ./coder.tar.gz --name coder
+```
+
+**Publish a distribution.** Package the profile as a **git repository** so recipients install it with one command and pull versioned updates later. Carries the SOUL, config, skills, cron jobs, and MCP connections; credentials, memories, and sessions stay per-machine.
+
+```bash
+# Install a whole agent from a git repo
+hermes profile install github.com/you/research-bot --alias
+
+# Update later when the author ships a new version (keeps your memories + .env)
+hermes profile update research-bot
+```
+
+Use an export file for a one-time handoff or a move; use a distribution for an agent you'll keep shipping. See **[Profile Distributions: Share a Whole Agent](./profile-distributions.md)** for both — the comparison table, authoring, publishing, update semantics, and the security model.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/secrets/bitwarden.md

@@ -0,0 +1,155 @@
+# Bitwarden Secrets Manager
+
+Pull API keys from [Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/) at process startup instead of storing them in plaintext inside `~/.hermes/.env`. One bootstrap secret (a machine-account access token) replaces N per-provider keys, and rotating a credential becomes a single change in the Bitwarden web app.
+
+## How it works
+
+1. You create a **machine account** in Bitwarden Secrets Manager, give it read access to a project, and generate an **access token**.
+2. Hermes stores that single token in `~/.hermes/.env` as `BWS_ACCESS_TOKEN`.
+3. Every time `hermes` (or the gateway, or a cron job) starts, after `~/.hermes/.env` has loaded, Hermes calls `bws secret list <project_id>` and sets the returned keys into `os.environ`.
+4. By default Hermes **overrides** values already in your environment, so Bitwarden is the source of truth — rotate a key once in the web app and every Hermes process picks it up on next start. Flip `override_existing: false` in config if you want `.env` to win instead.
+
+The `bws` binary is auto-downloaded into `~/.hermes/bin/` on first use — no `apt`, no `brew`, no `sudo`.
+
+## Why machine accounts (and why no 2FA prompt)
+
+Bitwarden Secrets Manager is designed for non-interactive workloads: machine accounts can't be 2FA-gated because there's no human in the loop. The access token is the credential. Anyone with it can read every secret the machine account has access to, so treat it like a high-value bearer token — store it in `.env` (not `config.yaml`), and revoke + regenerate from the Bitwarden web app if it ever leaks.
+
+You set up the machine account *in the web app*, where your normal 2FA applies. After that the token is autonomous.
+
+## Setup
+
+### 1. Create a machine account and access token
+
+In the [Bitwarden web app](https://vault.bitwarden.com) (or [vault.bitwarden.eu](https://vault.bitwarden.eu) for EU accounts):
+
+1. Switch to **Secrets Manager** from the product switcher.
+2. Create or pick a **Project** (e.g. "Hermes keys").
+3. Add your provider keys as secrets. The secret **Name** becomes the environment variable name — use `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, etc.
+4. **Machine accounts → New machine account → My Hermes machine** → **Projects** tab → grant Read access to your project.
+5. **Access tokens** tab → **Create access token** → **Never** expires (or pick a date) → copy the token (starts with `0.`). Bitwarden cannot retrieve it again — keep the copy.
+
+Secrets Manager is included on the Bitwarden free tier with limits; no paid plan needed to try this.
+
+### 2. Run the wizard
+
+```bash
+hermes secrets bitwarden setup
+```
+
+It will:
+
+1. Download and verify `bws v2.0.0` into `~/.hermes/bin/bws`.
+2. Prompt you for the access token (input is hidden). Stored in `~/.hermes/.env` as `BWS_ACCESS_TOKEN`.
+3. Ask which Bitwarden region your machine account belongs to — **US Cloud**, **EU Cloud**, or **self-hosted / custom URL**. Stored in `config.yaml` as `secrets.bitwarden.server_url` and passed to `bws` as `BWS_SERVER_URL`.
+4. List the projects the machine account can see; pick one. Stored in `config.yaml` as `secrets.bitwarden.project_id`.
+5. Test-fetch the project's secrets and show you which env vars will resolve.
+6. Flip `secrets.bitwarden.enabled: true`.
+
+Non-interactive setup is also supported via flags:
+
+```bash
+hermes secrets bitwarden setup \
+  --access-token "$BWS_ACCESS_TOKEN" \
+  --server-url https://vault.bitwarden.eu \
+  --project-id <project-uuid>
+```
+
+### 3. Confirm
+
+```bash
+hermes secrets bitwarden status
+```
+
+From now on, every `hermes` invocation pulls fresh secrets at startup. You'll see a one-line summary in stderr the first time secrets are applied in a process.
+
+## CLI
+
+| Command | What it does |
+|---|---|
+| `hermes secrets bitwarden setup` | Interactive wizard (install binary, prompt for token, pick project, test fetch) |
+| `hermes secrets bitwarden status` | Show config + binary version + token presence/validation |
+| `hermes secrets bitwarden token` | Rotate the access token: validate the new token against Bitwarden, then store it in `.env` |
+| `hermes secrets bitwarden sync` | Dry-run: pull secrets now and show what would be applied |
+| `hermes secrets bitwarden sync --apply` | Pull and export into the current shell's environment |
+| `hermes secrets bitwarden install` | Just download the pinned `bws` binary (no auth required) |
+| `hermes secrets bitwarden disable` | Flip `enabled: false`; leaves token + project id in place |
+
+## Rotating an expired or revoked token
+
+When the machine-account token expires, gets revoked, or the account is deleted, startup shows:
+
+```
+Bitwarden Secrets Manager: Bitwarden rejected the machine-account access token (BWS_ACCESS_TOKEN) — it was likely revoked, expired, or belongs to another region.  (...)
+Bitwarden Secrets Manager: → Run `hermes secrets bitwarden token` to paste a fresh access token ...
+```
+
+Fix it without re-running the whole wizard:
+
+```bash
+hermes secrets bitwarden token                     # masked prompt
+hermes secrets bitwarden token --access-token 0.…  # non-interactive
+```
+
+The command probes Bitwarden with the new token **before** writing anything — a rejected token leaves your current `.env` untouched. On success it stores the token, clears the fetch caches, and warns if the configured project is not visible to the new machine account.
+
+## Configuration
+
+Defaults in `~/.hermes/config.yaml`:
+
+```yaml
+secrets:
+  bitwarden:
+    enabled: false
+    access_token_env: BWS_ACCESS_TOKEN
+    project_id: ""
+    server_url: ""
+    cache_ttl_seconds: 300
+    encrypted_cache:
+      enabled: false
+      max_stale_seconds: 0
+    override_existing: true
+    auto_install: true
+```
+
+| Key | Default | What it does |
+|---|---|---|
+| `enabled` | `false` | Master switch. When false, Bitwarden is never contacted. |
+| `access_token_env` | `BWS_ACCESS_TOKEN` | Env var name that holds the bootstrap token. Change this if you already use `BWS_ACCESS_TOKEN` for something else. |
+| `project_id` | `""` | UUID of the project to sync from. |
+| `server_url` | `""` | Bitwarden region or self-hosted endpoint. Empty = `bws` default (US Cloud, `https://vault.bitwarden.com`). Set to `https://vault.bitwarden.eu` for EU Cloud, or your own URL for self-hosted. Plumbed into the `bws` subprocess as `BWS_SERVER_URL`. |
+| `cache_ttl_seconds` | `300` | How long an in-process or disk fetch result is reused. Set to `0` to disable fresh-cache reuse. |
+| `encrypted_cache.enabled` | `false` | Store the last successful fetch in an AES-GCM encrypted cache at `~/.hermes/cache/bws_cache.enc.json`. |
+| `encrypted_cache.max_stale_seconds` | `0` | When encrypted caching is enabled, allow that cache to be used only after network/timeout failures, up to this age. Authentication failures never use stale secrets. A successful encrypted write removes the legacy plaintext `cache/bws_cache.json`. |
+| `override_existing` | `true` | When true, Bitwarden values overwrite anything already in env (so rotation in the web app actually takes effect). Flip to `false` if you want `.env` / shell exports to win locally. |
+| `auto_install` | `true` | When true, `bws` is auto-downloaded into `~/.hermes/bin/` on first use. |
+
+## Failure modes
+
+Bitwarden never blocks Hermes startup. If anything goes wrong, you'll see a one-line warning in stderr and Hermes continues with whatever credentials `.env` already had:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `BWS_ACCESS_TOKEN is not set` | Enabled in config but token cleared from `.env` | Re-run `hermes secrets bitwarden setup` |
+| `Bitwarden rejected the machine-account access token … invalid_client` | Token revoked, expired, machine account deleted — or the token belongs to another region (e.g. EU token hitting the US identity endpoint) | Run `hermes secrets bitwarden token` to paste a fresh token; for region mismatches re-run setup and pick EU/self-hosted (or set `secrets.bitwarden.server_url`) |
+| `bws exited 1: invalid access token` | Token revoked or wrong | Run `hermes secrets bitwarden token` with a new token |
+| `bws timed out` | Network blocked or Bitwarden API slow | Check connectivity to `api.bitwarden.com` (or your `server_url`) |
+| `bws binary not available` | `auto_install: false` and `bws` not on PATH | Install manually from [github.com/bitwarden/sdk-sm/releases](https://github.com/bitwarden/sdk-sm/releases) or flip `auto_install` back on |
+| `Checksum mismatch` | Download corrupted or tampered | Re-run, will retry; if it persists, file an issue |
+
+Startup warnings now include a `→` remediation line telling you exactly which command fixes the failure.
+
+## Security notes
+
+- The bootstrap token (`BWS_ACCESS_TOKEN`) is itself sensitive — anyone with it can read every secret the machine account has access to. Treat it the same as any other API key.
+- Hermes will refuse to let Bitwarden overwrite the bootstrap token itself, even with `override_existing: true`. If you store `BWS_ACCESS_TOKEN` as a secret inside the project, it's silently skipped during apply.
+- The `bws` binary download is verified against the published SHA-256 checksum from the same GitHub release. Mismatch aborts the install.
+- The pinned version (`bws v2.0.0` at time of writing) is updated through PRs to this repo — Hermes does not auto-upgrade `bws` to "latest" because upstream release shapes can change.
+
+## When NOT to use this
+
+- **Single-machine personal setups** where `~/.hermes/.env` is fine. You're trading one credential for another and adding a network dependency at startup.
+- **Air-gapped environments** that can't reach `api.bitwarden.com`.
+- **CI/CD** where the existing secrets-injection mechanism (GitHub Actions secrets, Vault, etc.) is already set up — pick one path, not two.
+
+The good case for this is multi-machine fleets, shared dev boxes, gateway VPSes, or any setup where you want centralized rotation and revocation across multiple Hermes installations.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/secrets/command.md

@@ -0,0 +1,50 @@
+# Command Helper Secret Source
+
+Resolve credentials by running your own helper command at startup — any secret store with a CLI works: `keepassxc-cli`, `secret-tool` (GNOME Keyring), `pass`, `gpg`, Vaultwarden's CLI, or a script that cats a tmpfs env file. The helper prints `KEY=VALUE` lines on stdout; Hermes applies them through the same orchestrator as [Bitwarden](./bitwarden) and [1Password](./onepassword), so you can enable any combination of sources simultaneously.
+
+## How it works
+
+1. You configure a helper command in `config.yaml` (never in `.env` — the command is configuration, `.env` holds values).
+2. At startup, after `.env` loads, Hermes runs the helper ONCE via `/bin/sh -c` and parses its stdout as a dotenv blob.
+3. The parsed keys flow through the standard precedence ladder: `.env`/shell win unless `override_existing: true`; mapped sources beat this bulk source on contested vars; first claim wins.
+
+```yaml
+secrets:
+  command:
+    enabled: true
+    command: "cat /run/user/1000/hermes-secrets.env"
+    # or any vault CLI that dumps KEY=VALUE lines:
+    # command: "pass show hermes/env"
+    # command: "secret-tool lookup service hermes-env"
+```
+
+## Config
+
+| Key | Default | What it does |
+|---|---|---|
+| `enabled` | `false` | Master switch. |
+| `command` | `""` | Helper run via `/bin/sh -c`; must print `KEY=VALUE` lines on stdout. |
+| `helper_timeout_seconds` | `3` | Hard timeout for one helper run. Deliberately tight — the helper must be fast and NON-interactive (no unlock prompts, no touch/PIN). |
+| `override_existing` | `false` | Helper values overwrite `.env`/shell values. Off by default (unlike Bitwarden/1Password) since a local helper is not a central rotation authority. |
+
+## Security model
+
+- The helper command string is YOUR configuration — same trust level as the `.env` file you control.
+- Output is hard-capped at 1 MiB; a runaway helper can't wedge startup (process group killed on timeout).
+- The helper's **stderr is discarded** — vault CLI diagnostics can carry secret material, so they never reach Hermes' output. Failures log structured fields only (exit code / signal / errno), never the command string.
+- Whitespace-only values are treated as "no value" — a placeholder entry never flows into an Authorization header.
+- POSIX-only (needs `/bin/sh`). On Windows the source reports itself unconfigured and startup continues.
+
+## Failure modes
+
+Startup is never blocked. Errors print one line plus a `→` remediation hint:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `secrets.command.command is empty` | Enabled without a command | Set `secrets.command.command` in config.yaml |
+| `helper command failed` | Non-zero exit, timeout, spawn failure | Run the helper manually in a shell to see its real error (Hermes discards its stderr on purpose) |
+| `helper output was not a KEY=VALUE map` | Helper printed a bare value or garbage | Make the helper emit dotenv-shaped lines |
+
+## When to use this vs a plugin
+
+The command source is the escape hatch for vaults without a bundled integration. If you find yourself wrapping a complex CLI dance in a long script, consider a proper [secret-source plugin](/developer-guide/secret-source-plugin) instead — plugins get caching, provenance labels, and typed config.