@shadowob/cloud 1.1.6-dev.311

package/images/gemini-runner/RUNNER.md

@@ -0,0 +1,218 @@
+# Gemini Runner Research
+
+Research date: 2026-05-14.
+
+## Target role
+
+`gemini` should run through the ShadowOB `cc-connect` fork, not through OpenClaw
+gateway or ACPX. The runner process should be:
+
+```text
+cc-connect fork -> agent type "gemini" -> gemini CLI
+```
+
+Shadow transport should come from the cc-connect ShadowOB platform.
+
+## Current repository state
+
+The Gemini adapter and image now use the cc-connect fork path. The runtime
+package emits `cc-connect-config.toml`, `.gemini/settings.json`, `GEMINI.md`,
+workspace bootstrap files, and ShadowOB skill files through
+`runtime-files.json`.
+
+## Native Gemini CLI configuration
+
+Gemini CLI uses JSON settings files with explicit precedence:
+
+| Concern | Native Gemini CLI surface |
+| --- | --- |
+| System defaults | System-wide defaults file. |
+| User settings | `~/.gemini/settings.json`. |
+| Project settings | `.gemini/settings.json` in the project root. |
+| System overrides | `/etc/gemini-cli/settings.json` on Linux, platform equivalents on Windows/macOS. |
+| Context files | `.gemini` project directory and `GEMINI.md` discovery, configurable via context settings. |
+| Models/auth | Gemini model config, `GEMINI_API_KEY`, `GOOGLE_API_KEY`, Google auth options. |
+| MCP | `mcpServers.<SERVER_NAME>` in settings. |
+| Commands | Built-in slash commands and custom commands loaded from `.toml` command files. |
+| Hooks | `hooksConfig` plus hook arrays such as `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`, `SessionStart`, `SessionEnd`, `BeforeModel`, and `AfterModel`. |
+| Extensions | Extension install/load policy and extension settings. |
+| Checkpointing | `general.checkpointing.enabled`. |
+| Telemetry/logs | `telemetry.enabled`, `telemetry.target`, `telemetry.logPrompts`, `telemetry.outfile`, and debug env/flags. |
+
+The researched Gemini CLI docs do not describe a direct `SKILL.md` skill system
+like Codex, Claude Code, OpenCode, or Hermes. Treat skills as Cloud-authored
+prompts/context, Gemini extensions, or custom commands until a native Gemini
+skill standard exists.
+
+## Shadow slash command bridge
+
+The runner package always materializes `/etc/shadowob/slash-commands.json` so
+Shadow can load a stable command index. The Gemini runner owns its catalog in
+`apps/cloud/src/runtimes/slash-commands/gemini.ts`; this is intentionally not a
+common runtime artifact.
+
+Official Gemini CLI slash commands researched from the reference include
+`/about`, `/agents`, `/auth`, `/bug`, `/chat`, `/clear`, `/commands`,
+`/compress`, `/copy`, `/directory`, `/docs`, `/editor`, `/extensions`,
+`/help`, `/hooks`, `/ide`, `/init`, `/mcp`, `/memory`, `/model`,
+`/permissions`, `/plan`, `/policies`, `/privacy`, `/quit`, `/restore`,
+`/rewind`, `/resume`, `/settings`, `/shells`, `/setup-github`, `/skills`,
+`/stats`, `/terminal-setup`, `/theme`, `/tools`, `/upgrade`, and `/vim`.
+
+Current Cloud injection registers only names that do not collide with
+cc-connect's universal bot commands. Examples include `/about`, `/agents`,
+`/auth`, `/bug`, `/chat`, `/clear`, `/copy`, `/directory`, `/docs`, `/editor`,
+`/extensions`, `/hooks`, `/ide`, `/init`, `/mcp`, `/permissions`, `/plan`,
+`/policies`, `/privacy`, `/quit`, `/restore`, `/rewind`, `/resume`,
+`/settings`, `/shells`, `/setup-github`, `/stats`, `/terminal-setup`,
+`/theme`, `/tools`, and `/vim`. Overlapping names such as `/commands`,
+`/compress`, `/help`, `/memory`, `/model`, `/skills`, and `/upgrade` remain
+cc-connect-managed.
+
+cc-connect local commands are prompt-backed. Native Gemini TUI passthrough and
+custom TOML command discovery should be implemented inside the cc-connect Gemini
+agent before Cloud treats them as exact CLI control commands.
+
+## Schema and type anchors
+
+- Settings schema URL:
+  `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json`.
+- Schema `$id` matches that same raw GitHub URL and uses JSON Schema draft
+  2020-12.
+- Type surface: JSON `settings.json`, `.gemini` project files, command TOML
+  files, context file settings, and extension config.
+- cc-connect type anchor: `../cc-connect/agent/gemini/gemini.go`.
+- Test rule: generated `.gemini/settings.json` must validate against the schema
+  and then survive a Gemini CLI startup smoke test.
+
+## Provider and authentication notes
+
+- Gemini CLI has three primary auth families: Google login, Gemini API key, and
+  Vertex AI. Google login is recommended for AI Pro/Ultra subscription usage but
+  requires browser/localhost interaction, so it is not the default Cloud
+  bootstrap path.
+- AI Studio API-key mode uses `GEMINI_API_KEY`. Store it as a Kubernetes Secret
+  and never bake it into `.gemini/settings.json`.
+- Vertex AI needs `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`, then one
+  of ADC, a service-account JSON key, or `GOOGLE_API_KEY`. The docs require
+  unsetting `GOOGLE_API_KEY`/`GEMINI_API_KEY` when using ADC/service-account
+  flows.
+- Gemini CLI settings do not expose a generic OpenAI-compatible provider block.
+  A Cloud adapter that needs non-Google models must use a different runner or a
+  separate gateway integration instead of faking Gemini config keys.
+- Headless smoke tests should assert the selected auth mode and required env
+  keys without making a provider call unless the test environment explicitly
+  supplies real credentials.
+
+## Security, audit, cost, network, and tools
+
+- Approval: `general.defaultApprovalMode` supports `default`, `auto_edit`, and
+  `plan`; YOLO can only be enabled via CLI flags, so Cloud must not silently
+  encode YOLO in settings.
+- Tools: `tools.exclude`, custom tool discovery/call commands, and MCP
+  `includeTools`/`excludeTools` define the effective tool surface.
+- MCP: `mcpServers.<name>.trust = true` bypasses confirmations for that server;
+  do not emit it unless Cloud policy explicitly trusts the server.
+- Browser/network: browser agent `allowedDomains`, sensitive action
+  confirmation, upload blocking, and max actions per task are the main network
+  controls found in the schema.
+- Workspace trust: `security.folderTrust.enabled` and
+  `GEMINI_CLI_TRUST_THIS_FOLDER` matter for headless containers.
+- Secrets: `security.environmentVariableRedaction.*` and
+  `advanced.excludedEnvVars` should be generated when audit policy requires
+  env filtering.
+- Cost/audit: `model.maxSessionTurns`, `model.summarizeToolOutput.*.tokenBudget`,
+  telemetry `logPrompts`, telemetry target/outfile, and MCP tool count need
+  audit coverage.
+- Logs: shell history is under `~/.gemini/tmp/<project_hash>/shell_history`;
+  chat/session data is under Gemini's `~/.gemini/tmp/<project_hash>/chats/`.
+
+## cc-connect mapping
+
+The local fork exposes `core.RegisterAgent("gemini", New)`. Important options
+from `../cc-connect/agent/gemini/gemini.go`:
+
+- `work_dir`
+- `model`
+- `mode`: `default`, `auto_edit`, `yolo`, `plan`
+- `cmd`
+- `timeout_mins`
+
+The fork drives Gemini CLI with prompt mode and stream JSON output. It also knows
+how to list sessions from Gemini's native chat storage under
+`~/.gemini/tmp/<project_hash>/chats/`.
+
+Example generated project shape:
+
+```toml
+[[projects]]
+name = "agent-id"
+
+[projects.agent]
+type = "gemini"
+
+[projects.agent.options]
+work_dir = "/workspace"
+
+[[projects.platforms]]
+type = "shadowob"
+```
+
+## Capability notes
+
+- Models: map Cloud model preferences to Gemini CLI model selection and
+  provider environment variables.
+- Skills: no native `SKILL.md` surface was found; use `GEMINI.md`, custom
+  commands, and extensions for phase 1.
+- MCP: write `mcpServers` in `.gemini/settings.json`.
+- Cron/routine: no native CLI cron surface found in the researched config docs;
+  Cloud should own scheduling for phase 1.
+- Hooks: write `hooksConfig` and `hooks.*` in Gemini settings.
+- Subagents: Gemini settings expose agent override and hook points around agent
+  execution, but cc-connect currently drives the main Gemini CLI agent only.
+- Logs: use Gemini telemetry local output when enabled, Gemini native chat
+  storage, and cc-connect daemon logs.
+
+## Migration implications
+
+- OpenClaw, ACPX, and `@shadowob/openclaw-shadowob` are not used by the Gemini
+  runner image.
+- The image embeds the cc-connect fork plus `@google/gemini-cli`.
+- Generate `~/.gemini/settings.json`, project `.gemini/settings.json`,
+  `GEMINI.md`, custom command files, and MCP/telemetry settings as native
+  artifacts.
+- Runtime package smoke tests verify native config/file generation; a Docker
+  smoke should still verify Gemini CLI startup and stream JSON through
+  cc-connect before publishing an image tag.
+
+## Adapter and smoke tests
+
+Unit tests:
+
+- `.gemini/settings.json` validates against the official schema.
+- Approval mode, MCP trust/include/exclude, browser domain restrictions, upload
+  blocking, telemetry, and env redaction map correctly.
+- Skills are not emitted as fake `SKILL.md` Gemini config; they are represented
+  as context, command, or extension artifacts.
+- cc-connect TOML contains `type = "gemini"` and no OpenClaw artifacts.
+
+Container smoke:
+
+- `cc-connect --version` and `gemini --version` work.
+- `.gemini/settings.json`, `GEMINI.md`, command files, and extension files are
+  materialized.
+- Schema validation runs inside the container or in the package test before
+  image build.
+- Start cc-connect with `type = "gemini"` and inspect session/log paths.
+- Assert headless trust settings are explicit and no provider secret is printed.
+
+## Sources
+
+- Gemini CLI configuration:
+  https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md
+- Gemini CLI authentication:
+  https://google-gemini.github.io/gemini-cli/docs/get-started/authentication.html
+- Gemini CLI commands:
+  https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/commands.md
+- Gemini CLI repository: https://github.com/google-gemini/gemini-cli
+- cc-connect fork source: https://github.com/buggyblues/cc-connect

package/images/gemini-runner/entrypoint.mjs

@@ -0,0 +1,2 @@
+process.env.SHADOW_RUNNER_NAME ??= 'gemini-runner'
+await import('../cc-connect-runner/entrypoint.mjs')

package/images/hermes-runner/Dockerfile

@@ -0,0 +1,74 @@
+# syntax=docker/dockerfile:1.7
+
+# ─── Hermes Runner ────────────────────────────────────────────────────────
+# Native Hermes gateway runner with ShadowOB plugin materialized by Cloud.
+#
+# Build from the repository root:
+#   docker build -t ghcr.io/buggyblues/hermes-runner:latest \
+#     -f apps/cloud/images/hermes-runner/Dockerfile .
+# ──────────────────────────────────────────────────────────────────────────
+
+FROM nousresearch/hermes-agent:latest AS runner
+
+LABEL org.opencontainers.image.source="https://github.com/nicepkg/shadow"
+LABEL org.opencontainers.image.description="Shadow Cloud Hermes Runner"
+
+ARG NODE_VERSION=22.21.1
+
+USER root
+
+WORKDIR /app
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl xz-utils && \
+    rm -rf /var/lib/apt/lists/* && \
+    arch="$(dpkg --print-architecture)" && \
+    case "$arch" in \
+      amd64) node_arch="x64" ;; \
+      arm64) node_arch="arm64" ;; \
+      *) echo "Unsupported architecture for Node.js: $arch" >&2; exit 1 ;; \
+    esac && \
+    curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${node_arch}.tar.xz" \
+      -o /tmp/node.tar.xz && \
+    tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1 && \
+    rm -f /tmp/node.tar.xz && \
+    node --version
+
+RUN npm init -y && \
+    npm install --no-audit --fund=false @shadowob/cli@latest @shadowob/connector@latest && \
+    ln -sf /opt/hermes/.venv/bin/hermes /usr/local/bin/hermes && \
+    ln -s /app/node_modules/.bin/shadowob /usr/local/bin/shadowob && \
+    ln -s /app/node_modules/.bin/shadowob-connector /usr/local/bin/shadowob-connector
+
+RUN existing_user="$(getent passwd 1000 | cut -d: -f1 || true)" && \
+    if [ -n "$existing_user" ]; then \
+      if command -v groupmod >/dev/null 2>&1; then groupmod -n shadow "$existing_user" 2>/dev/null || true; fi; \
+      usermod -l shadow -d /home/shadow -m "$existing_user" 2>/dev/null || true; \
+    else \
+      groupadd -g 1000 shadow 2>/dev/null || groupadd shadow; \
+      useradd -u 1000 -g shadow -m -d /home/shadow -s /usr/sbin/nologin shadow; \
+    fi && \
+    mkdir -p /home/shadow/.hermes /etc/openclaw /etc/shadowob /var/log/shadowob \
+             /workspace /tmp/npm-cache && \
+    if [ ! -e /home/openclaw ]; then ln -s /home/shadow /home/openclaw; fi && \
+    chown -R 1000:1000 /home/shadow /etc/shadowob /var/log/shadowob \
+      /workspace /tmp/npm-cache /app
+
+COPY --chown=1000:1000 apps/cloud/images/hermes-runner/entrypoint.mjs /app/entrypoint.mjs
+
+HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
+  CMD curl -f http://localhost:3100/health || exit 1
+
+EXPOSE 3100
+
+ENV NODE_ENV=production
+ENV HOME=/home/shadow
+ENV SHADOW_RUNNER_HEALTH_PORT=3100
+ENV OPENCLAW_NO_RESPAWN=1
+ENV HERMES_HOME=/home/shadow/.hermes
+ENV npm_config_cache=/tmp/npm-cache
+
+USER shadow
+
+ENTRYPOINT ["tini", "--"]
+CMD ["node", "/app/entrypoint.mjs"]

package/images/hermes-runner/RUNNER.md

@@ -0,0 +1,243 @@
+# Hermes Runner Research
+
+Research date: 2026-05-14.
+
+## Target role
+
+`hermes` is a new Cloud runner. It should run Hermes Agent's native gateway with
+the bundled ShadowOB Hermes platform plugin, not OpenClaw and not cc-connect:
+
+```text
+hermes gateway -> shadowob Hermes platform plugin
+```
+
+This directory now contains the Hermes runner Dockerfile and entrypoint. The
+runtime loader and package generator emit Hermes-native files through
+`runtime-files.json` and keep ShadowOB token material in Kubernetes Secret data.
+
+## Native Hermes configuration
+
+Hermes stores its runtime state under `~/.hermes/`:
+
+| Concern | Native Hermes surface |
+| --- | --- |
+| Main config | `~/.hermes/config.yaml`. |
+| Secrets | `~/.hermes/.env`. |
+| Auth | `~/.hermes/auth.json`. |
+| Personality | `~/.hermes/SOUL.md`. |
+| Memory | `~/.hermes/memories/`. |
+| Skills | `~/.hermes/skills/`, managed by Hermes skill tools. |
+| Cron | `~/.hermes/cron/jobs.json` and outputs under `~/.hermes/cron/output/<job_id>/<timestamp>.md`. |
+| Sessions | `~/.hermes/sessions/`. |
+| Logs | `~/.hermes/logs/`, including gateway/error logs with secret redaction. |
+| Plugins | `~/.hermes/plugins/` and `plugins.enabled` in config. |
+
+Hermes supports local, Docker, SSH, Modal, Daytona, Vercel Sandbox, and
+Singularity/Apptainer terminal backends. The Cloud runner should start with a
+container-local backend and explicitly decide later whether to expose remote
+backends.
+
+## Schema and type anchors
+
+- Static JSON Schema URL: none found in the official docs.
+- Runtime schema source: Hermes web dashboard docs say all config fields are
+  auto-discovered from `DEFAULT_CONFIG` and exposed through `GET
+  /api/config/schema`.
+- Config type: YAML `config.yaml` plus `.env` and profile directories.
+- Plugin type anchor: `packages/connector/hermes-shadowob-plugin/plugin.yaml`
+  and its adapter code.
+- Test rule: generated `config.yaml` must parse as YAML, load through Hermes,
+  and, when the dashboard/API is enabled, match the runtime schema endpoint.
+
+## Provider and authentication notes
+
+- Hermes requires at least one inference provider. The interactive
+  `hermes model` flow can configure providers, but Cloud should generate
+  `~/.hermes/config.yaml` and `~/.hermes/.env` directly from deployment
+  provider refs.
+- Official provider paths include Nous Portal OAuth/subscription, Codex ChatGPT
+  OAuth, GitHub Copilot OAuth or tokens, Anthropic OAuth/API key/manual token,
+  OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, and other provider-specific
+  API keys.
+- API-key providers belong in `~/.hermes/.env`, for example
+  `OPENROUTER_API_KEY`, `AI_GATEWAY_API_KEY`, or provider-specific keys. The
+  adapter must not place raw model keys in ConfigMaps.
+- Custom provider/base-url routing belongs in Hermes `model.default`,
+  `model.provider`, and `model.base_url` fields, plus routing/fallback config
+  when enabled.
+- Hermes model auth and ShadowOB platform auth are separate. `SHADOW_TOKEN`
+  enables the messaging platform plugin; model provider keys enable inference.
+
+## Models, tools, and extensions
+
+| Concern | Hermes feature |
+| --- | --- |
+| Models | Primary model slots plus auxiliary models for side jobs. Providers include Nous Portal, OpenRouter, OpenAI, Anthropic, Google, and OpenAI-compatible endpoints. |
+| Skills | Built-in and user-created skills with progressive disclosure, skill management, and curator maintenance. |
+| MCP | Hermes MCP feature with server and tool filtering. |
+| Cron/routine | Native cron jobs via `/cron`, `hermes cron`, and the `cronjob` tool; jobs can attach one or more skills. |
+| Hooks | Plugin lifecycle hooks such as session start/end and tool/agent lifecycle callbacks. |
+| Subagents | `delegate_task`, child agents, Kanban multi-agent board, and profile/worktree patterns. |
+| Logs | Native logs in `~/.hermes/logs`; cron outputs are separate durable markdown artifacts. |
+
+## Security, audit, cost, network, and tools
+
+- User authorization: gateway access is deny-by-default unless allowlists,
+  pairing, or explicit allow-all are configured.
+- Command approvals: `approvals.mode` supports `manual`, `smart`, and `off`;
+  `off` is equivalent to yolo and should be blocked by Cloud policy unless
+  explicitly requested.
+- Hardline blocklist: catastrophic commands are denied even in yolo/off modes.
+- Containers: Docker backend drops capabilities, sets no-new-privileges, caps
+  PIDs, and uses tmpfs for temp dirs; Cloud should start here for production
+  gateway deployments.
+- Resources: container CPU, memory, disk, and persistence flags belong in
+  `terminal.*` config and must be auditable.
+- Secrets: terminal/docker env passthrough is explicit allowlist only; credential
+  files are mounted read-only when declared by skills.
+- MCP: Hermes filters MCP environment separately from terminal passthrough; use
+  MCP `env` config for MCP secrets.
+- Cost/audit: native cron jobs, tool gateway use, delegate/subagent work,
+  auxiliary models, container resources, and logs under `~/.hermes/logs` need
+  Cloud audit labels.
+- Network: provider endpoints, tool gateway, MCP remote endpoints, messaging
+  platform endpoints, and Docker/remote backend egress should be captured in the
+  runner package.
+
+## Shadow integration
+
+The repository already includes a Hermes ShadowOB platform plugin at
+`packages/connector/hermes-shadowob-plugin`. It currently supports:
+
+- channel, direct, and thread inbound messages
+- outbound text and media replies
+- Socket.IO receive with REST polling fallback
+- startup catch-up window
+- typing/activity and heartbeat status
+- dynamic channel and policy discovery through Shadow APIs
+- optional slash command registration through `SHADOW_SLASH_COMMANDS_JSON`
+- the runner package materializes `/etc/shadowob/slash-commands.json` from the
+  Hermes-owned catalog in `apps/cloud/src/runtimes/slash-commands/hermes.ts`
+- interactive component metadata forwarding
+- cron/send_message delivery through `SHADOW_HOME_CHANNEL`
+
+Hermes publishes both CLI and messaging slash command surfaces. Researched CLI
+commands include session commands such as `/new`, `/clear`, `/history`,
+`/save`, `/retry`, `/undo`, `/compress`, `/rollback`, `/queue`, `/steer`,
+`/goal`, `/resume`, `/sessions`, `/agents`, `/background`, and `/branch`;
+configuration commands such as `/model`, `/codex-runtime`, `/personality`,
+`/verbose`, `/fast`, `/reasoning`, `/skin`, `/statusbar`, `/voice`, `/yolo`,
+`/footer`, and `/busy`; tool commands such as `/tools`, `/toolsets`,
+`/browser`, `/skills`, `/cron`, `/curator`, `/kanban`, `/reload-mcp`,
+`/reload-skills`, and `/plugins`; and info/exit commands such as `/usage`,
+`/platforms`, `/paste`, `/copy`, `/image`, `/debug`, `/profile`, `/gquota`,
+and `/quit`.
+
+Current Cloud injection exposes the messaging-safe subset documented by Hermes:
+`/new`, `/reset`, `/status`, `/stop`, `/model`, `/codex-runtime`,
+`/personality`, `/fast`, `/retry`, `/undo`, `/sethome`, `/compress`, `/title`,
+`/resume`, `/usage`, `/insights`, `/reasoning`, `/voice`, `/rollback`,
+`/background`, `/queue`, `/steer`, `/goal`, `/footer`, `/curator`, `/kanban`,
+`/reload-mcp`, `/yolo`, `/commands`, `/approve`, `/deny`, `/update`,
+`/restart`, `/debug`, and `/help`. Hermes documents `/cron` as CLI-only, so it
+is not registered into Shadow until the gateway supports messaging cron safely.
+
+Example generated config:
+
+```yaml
+plugins:
+  enabled:
+    - shadowob
+
+platforms:
+  shadowob:
+    enabled: true
+    token: "${SHADOW_TOKEN}"
+    extra:
+      base_url: "${SHADOW_BASE_URL}"
+      mention_only: false
+      rest_only: false
+      catchup_minutes: 0
+      download_media: true
+      slash_commands: []
+```
+
+Required environment:
+
+```bash
+SHADOW_BASE_URL=<shadow-api-url>
+SHADOW_TOKEN=...
+```
+
+## Capability notes
+
+- Models: generate Hermes provider/model config natively in `config.yaml`.
+- Skills: materialize Hermes skills under `~/.hermes/skills` when Cloud owns the
+  runner profile.
+- MCP: write Hermes MCP config rather than OpenClaw or Codex MCP formats.
+- Cron/routine: Hermes has the strongest native cron surface among the target
+  runners; keep cron jobs in Hermes native storage when the agent runtime is
+  Hermes.
+- Hooks: expose plugin hooks through `plugins.enabled` and plugin files, not a
+  central OpenClaw hook adapter.
+- Subagents: support Hermes delegation later as native Hermes multi-agent
+  features, not as OpenClaw `agents.list`.
+- Logs: collect `~/.hermes/logs` and cron output directories separately.
+
+## Migration implications
+
+- `hermes` is included in the `AgentRuntime` schema and runtime loader.
+- `hermes-runner` installs Hermes Agent, ShadowOB CLI/connector packages, and
+  copies/enables the ShadowOB Hermes plugin.
+- Generate `~/.hermes/config.yaml`, `.env`, `SOUL.md`, skills, MCP config, and
+  cron config as native artifacts.
+- Keep this runner out of the cc-connect narrowed binary. Hermes already has a
+  native gateway/platform plugin boundary.
+- Runtime package smoke tests verify Hermes config/file generation; an
+  end-to-end Docker smoke should still start `hermes gateway`, resolve the Buddy
+  id through Shadow, register slash commands, and send a DM response before
+  publishing an image tag.
+
+## Adapter and smoke tests
+
+Unit tests:
+
+- `config.yaml` parses and contains expected provider/model, terminal,
+  approvals, gateway, plugin, MCP, cron, and skill fields.
+- ShadowOB plugin env/config is generated from Cloud fields without leaking
+  `SHADOW_TOKEN` into non-secret config.
+- `approvals.mode: off`, allow-all gateway access, unrestricted env passthrough,
+  and persistent containers require explicit Cloud policy opt-in.
+- Cron jobs use sanitized IDs and cannot write outside the Hermes cron store.
+
+Container smoke:
+
+- `hermes --version` works and plugin dependencies are installed.
+- `hermes gateway` starts with `plugins.enabled: ["shadowob"]`.
+- `~/.hermes/config.yaml`, `.env`, `SOUL.md`, `skills`, `cron`, `sessions`, and
+  `logs` directories are created.
+- Dashboard/API schema endpoint is checked when enabled.
+- Logs show plugin startup and deny/allow policy without raw Shadow token.
+
+## Sources
+
+- Hermes docs index: https://hermes-agent.nousresearch.com/docs/llms.txt
+- Configuration:
+  https://hermes-agent.nousresearch.com/docs/user-guide/configuration
+- Security: https://hermes-agent.nousresearch.com/docs/user-guide/security
+- Tool gateway:
+  https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway
+- Configuring models:
+  https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models
+- AI providers:
+  https://hermes-agent.nousresearch.com/docs/integrations/providers
+- Skills:
+  https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
+- MCP: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp
+- Cron: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
+- Hooks: https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks
+- Delegation:
+  https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation
+- Sessions: https://hermes-agent.nousresearch.com/docs/user-guide/sessions
+- Slash commands:
+  https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/slash-commands.md