Merge pull request #42 from zloeber/zloeber/claw_integration

feat: agent adopt for Hermes and OpenClaw installs

Author: zloeber

.mex/ROUTER.md

@@ -14,7 +14,7 @@ edges:
     condition: when setting up the dev environment or running the project for the first time
   - target: patterns/INDEX.md
     condition: when starting a task — check the pattern index for a matching pattern file
-last_updated: 2026-05-22
+last_updated: 2026-05-27
 ---
 
 # Session Bootstrap
@@ -54,7 +54,8 @@ Then read this file fully before doing anything else in this session.
 - **Safe provider retrieval CLI:** `secretzero get` now retrieves via provider bundle methods (`SyncEngine.get_provider_secret`) with metadata-first output by default; plaintext requires `--reveal`. Sandbox policy guards retrieval when `SZ_SANDBOX=true` unless explicitly overridden by `SZ_ALLOW_GET_IN_SANDBOX=true`, and command-level policy preflight blocks on policy errors.
 - **GitNexus / MetaGit relational intel:** `secretzero sync` and `secretzero get` write `.gitnexus/secrets_overlay.json` (Ladybug-oriented JSON linking manifest secret names to symbol IDs / FQNs from `.gitnexus/discovery_bindings.json`). Optional `SZ_METAGIT_REGISTRY=1` merges inventory into `~/.metagit.yml`. `secretzero discover` persists bindings and extends LLM output with parent symbol / FQN fields. `secretzero gitnexus blast-radius --symbol <FQN>` wraps GitNexus impact; `secretzero rotate --trigger-reindex` runs `gitnexus analyze --skills` after success. Per-secret `process_tags` labels execution-flow sensitivity (schema + docs updated).
 - **Terraform static-variable behavior:** Terraform export now always emits sensitive input variables for static-like secrets (`static` and bundle kinds with `PROMPTS_LIKE_STATIC`, such as `azure_app_reg`). `--include-static-secrets` now controls whether static defaults are embedded as Terraform variable defaults.
-- **Agent skill guidance split:** SecretZero guidance is now split into focused skills — `skills/secretzero-author/SKILL.md` (schema-compliant Secretfile authoring, safe contextless discovery, `.szvar` lane breakout, and policy-bound targets), `skills/secretzero-agent/SKILL.md` (agentic vectors, runtime/API workflows, and installation/onboarding), and `skills/secretzero-handle/SKILL.md` (`SZ_AGENT_MODE`, `.env`/ingest preseed, spill-safe CLI).
+- **Agent skill guidance split:** SecretZero guidance is now split into focused skills — `skills/secretzero-author/SKILL.md` (schema-compliant Secretfile authoring, safe contextless discovery, `.szvar` lane breakout, and policy-bound targets), `skills/secretzero-agent/SKILL.md` (agentic vectors, runtime/API workflows, and installation/onboarding), `skills/secretzero-handle/SKILL.md` (`SZ_AGENT_MODE`, `.env`/ingest preseed, spill-safe CLI), and `skills/secretzero-agent-adopt/SKILL.md` (Hermes/OpenClaw `agent list` / `agent adopt` bootstrap and restore loops).
+- **`secretzero agent list` / `agent adopt`:** Discover local Hermes/OpenClaw installs (read-only) and bootstrap SecretZero environments from **present** catalog credentials without emitting values. `agent adopt` writes `Secretfile.yml` into `--output-dir` (default: agent install path); `agent backup` is an alias. Supports `--template`, `--preseed-lockfile`, autodetect (Hermes then OpenClaw), and idempotent merge on re-adopt. See `docs/superpowers/specs/2026-05-27-agent-adopt-design.md`, `.mex/patterns/agent-adopt.md`.
 - **`secretzero agent instructions`:** Read-only Rich/JSON report of `agent_instructions` (summary + numbered steps). Default scope is pending manual secrets (same semantics as `agent sync`); `--all` lists every secret with instructions; `--detailed` adds optional metadata. See `.mex/patterns/agent-instructions-report.md`.
 - **Environment-map lanes + target profiles:** Secretfile now supports top-level `environments` and `target_profiles`; CLI (`sync`, `agent sync`, `web`) and API (`/sync`, `/agent/sync`) resolve lane-specific var files/lockfiles/profile defaults with runtime flags taking precedence. `secretzero web` now renders an environment dropdown and recomputes lane context on selection.
 - **CLI-wide environment propagation:** Secretfile-backed CLI commands now share root-aware `--environment` resolution. `secretzero -e <env> ...` flows into manifest/list/status/render/drift/terraform-style commands, while subcommand-local `--environment` overrides the root selection when both are present.

.mex/patterns/INDEX.md

@@ -5,6 +5,7 @@ Lookup table for all pattern files in this directory. Check here before starting
 | Pattern | Use when |
 |---------|----------|
 | [agent-sync.md](agent-sync.md) | Changing unified `agent sync` / `POST /agent/sync` (three vectors, CLI+API parity) |
+| [agent-adopt.md](agent-adopt.md) | `secretzero agent list` / `agent adopt` / Hermes-OpenClaw install bootstrap |
 | [agent-instructions-report.md](agent-instructions-report.md) | `secretzero agent instructions` pending/all report output |
 | [add-bundle.md](add-bundle.md) | Adding a provider/generator/target through bundle manifest registration |
 | [add-cli-command.md](add-cli-command.md) | Adding or changing `secretzero` CLI commands/options |

.mex/patterns/agent-adopt.md

@@ -0,0 +1,55 @@
+---
+name: agent-adopt
+description: Agent runtime adopt/list workflows for Hermes, OpenClaw, and future claw-like installs.
+triggers:
+  - "agent adopt"
+  - "agent list"
+  - "agent backup"
+  - "hermes adopt"
+  - "openclaw adopt"
+edges:
+  - target: patterns/add-cli-command.md
+    condition: when changing CLI flags or output shapes
+  - target: patterns/sz-agent-mode-spill-guard.md
+    condition: when touching agent-safe JSON or spill guards
+  - target: patterns/docs-entrypoint-parity.md
+    condition: when updating README/skills onboarding
+last_updated: 2026-05-27
+---
+
+# Agent Adopt Workflow
+
+## Context
+
+`secretzero agent list` and `secretzero agent adopt` (alias `agent backup`) bootstrap SecretZero
+environments from local agent installs. This is **not** `secretzero backup create` (encrypted value DR).
+
+Implementation lives under `src/secretzero/integrations/`.
+
+## Steps
+
+1. Add or extend an adapter in `integrations/<target>/` with `catalog.yaml` + `adapter.py`.
+2. Register the adapter in `integrations/registry.py` with autodetect order.
+3. Keep scans **presence-only** — never attach secret values to result models or JSON.
+4. Generated manifests use `default: null` on static secrets; target paths point at agent `.env` (absolute when GitOps output dir differs from install root).
+5. `--preseed-lockfile` must call `run_lockfile_import` via the ingest-preseed path (hash-only).
+6. Update skills (`secretzero-agent-adopt`), README `agent-entrypoint` comment, and ROUTER.md together.
+
+## Gotchas
+
+- `agent backup` wording collides mentally with `secretzero backup create` — document the distinction in help and skills.
+- Re-adopt merges new catalog matches into an existing Secretfile unless `--force`.
+- `--force` rebuilds from scratch (drops merge behavior).
+- Autodetect failure must not write partial artifacts.
+- Default `--output-dir` is the resolved agent install path.
+
+## Verify
+
+- Run `tests/test_agent_adopt.py`.
+- Confirm JSON output never contains fixture secret strings.
+- Run fast pre-commit gate.
+
+## Update Scaffold
+
+- [ ] Update `.mex/ROUTER.md` when adopt behavior changes
+- [ ] Keep `docs/superpowers/specs/2026-05-27-agent-adopt-design.md` aligned

README.md

@@ -1,4 +1,32 @@
 # SecretZero™
+<!-- agent-entrypoint:
+intent: executable-tool
+primary_workflow: usage-first
+install: uv tool install -U "secretzero[all]"
+
+bootstrap:
+  - export SZ_AGENT_MODE=true
+  - secretzero agent list --format json
+  - secretzero agent adopt --dry-run --format json
+
+authoritative:
+  - ./AGENTS.md
+
+usage:
+  - ./README.md#agent-quick-start
+  - ./skills/secretzero-agent-adopt/SKILL.md
+
+agent_targets:
+  discover: secretzero agent list --format json
+  adopt: secretzero agent adopt --format json
+  adopt_gitops: secretzero agent adopt --output-dir ./agents/hermes --template --format json
+  sync: secretzero agent sync --json
+  skills:
+    - skills/secretzero-agent-adopt/SKILL.md
+    - skills/secretzero-agent/SKILL.md
+    - skills/secretzero-handle/SKILL.md
+-->
+[test](./AGENTS.md)
 <div align="center">
 <a href="https://secret0.com/">
 <img src="docs/inc/secret0_angel_small.png" width="520" alt="Secret0 logo">
@@ -29,8 +57,22 @@ SecretZero is a secrets as code management tool that automates the creation, see
 If you are an agent reading this repository remotely through `gh`, `curl`, or a GitHub/MCP client,
 start here.
 
+**Agent runtime integration (Hermes / OpenClaw):**
+
+```bash
+export SZ_AGENT_MODE=true
+secretzero agent list --format json
+secretzero agent adopt --dry-run --format json
+secretzero agent adopt --preseed-lockfile --format json
+secretzero agent sync --json -f ~/.hermes/Secretfile.yml
+```
+
+See `skills/secretzero-agent-adopt/SKILL.md` for the full adopt/restore loop. `secretzero agent backup`
+is an alias of `agent adopt` (not `secretzero backup create`).
+
 Skill files:
 
+- `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md`
 - `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md`
 - `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md`
 - `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md`
@@ -53,6 +95,7 @@ Use that downloader like this:
 Direct Hermes install:
 
 ```bash
+hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md
@@ -176,8 +219,9 @@ uv tool install "secretzero[all]"
 
 ### Agent Skills
 
-SecretZero ships three focused skills for agentic workflows:
+SecretZero ships four focused skills for agentic workflows:
 
+- [`secretzero-agent-adopt`](./skills/secretzero-agent-adopt/SKILL.md) for Hermes/OpenClaw adopt/list, restore, and GitOps capture
 - [`secretzero-agent`](./skills/secretzero-agent/SKILL.md) for runtime bootstrap, `agent sync`, and secure human-in-the-loop operations
 - [`secretzero-author`](./skills/secretzero-author/SKILL.md) for `Secretfile.yml` authoring, review, and safe discovery workflows
 - [`secretzero-handle`](./skills/secretzero-handle/SKILL.md) for `.env` / file-target workflows, `SZ_AGENT_MODE`, and spill-safe CLI usage
@@ -195,6 +239,7 @@ secretzero agent sync --help
 If you are running Hermes Agent, install the skills directly from this repository:
 
 ```bash
+hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md
@@ -213,6 +258,7 @@ If you are running OpenClaw, opening this repository as the agent workspace is e
 
 ```bash
 mkdir -p ~/.agents/skills
+cp -R skills/secretzero-agent-adopt ~/.agents/skills/
 cp -R skills/secretzero-agent ~/.agents/skills/
 cp -R skills/secretzero-author ~/.agents/skills/
 cp -R skills/secretzero-handle ~/.agents/skills/

agents/hermes/.gitsecrets.lock

@@ -0,0 +1,78 @@
+{
+  "version": "1.0",
+  "secrets": {
+    "slack_bot_token": {
+      "hash": "883ba1bbba18a308675a68dbc4748bb1f6776828c09b74509e09453f3619cf6b",
+      "created_at": "2026-05-29T16:17:54.178698+00:00",
+      "updated_at": "2026-05-29T16:17:54.178698+00:00",
+      "last_rotated": null,
+      "rotation_count": 0,
+      "targets": {
+        "local/file//Users/zacharyloeber/.hermes/.env": "883ba1bbba18a308675a68dbc4748bb1f6776828c09b74509e09453f3619cf6b"
+      },
+      "target_provenance": {
+        "local/file//Users/zacharyloeber/.hermes/.env": [
+          {
+            "updated_at": "2026-05-29T16:17:54.179156+00:00",
+            "actor": {
+              "operation": "lockfile_import",
+              "client": "cli"
+            }
+          }
+        ]
+      }
+    },
+    "slack_app_token": {
+      "hash": "44f8da714c12516fd267eca3dbd8dfa05e7a2e3eeec653b1ca503f67a7e3120e",
+      "created_at": "2026-05-29T16:17:54.179248+00:00",
+      "updated_at": "2026-05-29T16:17:54.179248+00:00",
+      "last_rotated": null,
+      "rotation_count": 0,
+      "targets": {
+        "local/file//Users/zacharyloeber/.hermes/.env": "44f8da714c12516fd267eca3dbd8dfa05e7a2e3eeec653b1ca503f67a7e3120e"
+      },
+      "target_provenance": {
+        "local/file//Users/zacharyloeber/.hermes/.env": [
+          {
+            "updated_at": "2026-05-29T16:17:54.179253+00:00",
+            "actor": {
+              "operation": "lockfile_import",
+              "client": "cli"
+            }
+          }
+        ]
+      }
+    },
+    "telegram_bot_token": {
+      "hash": "dc2180c7edb6c480df54cea330d1a28e8104b2abf9c70089fced93b44ee33371",
+      "created_at": "2026-05-29T16:17:54.179336+00:00",
+      "updated_at": "2026-05-29T16:17:54.179336+00:00",
+      "last_rotated": null,
+      "rotation_count": 0,
+      "targets": {
+        "local/file//Users/zacharyloeber/.hermes/.env": "dc2180c7edb6c480df54cea330d1a28e8104b2abf9c70089fced93b44ee33371"
+      },
+      "target_provenance": {
+        "local/file//Users/zacharyloeber/.hermes/.env": [
+          {
+            "updated_at": "2026-05-29T16:17:54.179340+00:00",
+            "actor": {
+              "operation": "lockfile_import",
+              "client": "cli"
+            }
+          }
+        ]
+      }
+    }
+  },
+  "secretfile": {
+    "filename": "Secretfile.yml",
+    "hash": "a301c5974a64ddd6981cbe4809cbd34b05add6a7e54e210816e2a045ea64720b",
+    "synced_at": "2026-05-29T16:17:54.179346+00:00",
+    "var_files": [],
+    "variables_hash": "01b6fd0f13b7bc98a6b163ba9ff4dc2fe87cbe864faba9400722a10ca61471bc",
+    "sync_identity": null,
+    "manifest_spec_version": "1"
+  },
+  "metadata": {}
+}

agents/hermes/Secretfile.yml

@@ -0,0 +1,53 @@
+# yaml-language-server: $schema=https://github.com/zloeber/SecretZero/raw/refs/heads/main/Secretfile.schema.json
+metadata:
+  project: hermes-agent
+  owner: agent-operator
+  annotations:
+    secretzero.integration.target: hermes
+    secretzero.integration.source: /Users/zacharyloeber/.hermes
+variables:
+  agent_home: /Users/zacharyloeber/.hermes
+providers:
+  local:
+    kind: local
+    config: {}
+secrets:
+- name: slack_bot_token
+  kind: static
+  description: hermes credential for SLACK_BOT_TOKEN
+  config:
+    default: null
+  targets:
+  - provider: local
+    kind: file
+    config:
+      path: /Users/zacharyloeber/.hermes/.env
+      format: dotenv
+      key: SLACK_BOT_TOKEN
+      merge: true
+- name: slack_app_token
+  kind: static
+  description: hermes credential for SLACK_APP_TOKEN
+  config:
+    default: null
+  targets:
+  - provider: local
+    kind: file
+    config:
+      path: /Users/zacharyloeber/.hermes/.env
+      format: dotenv
+      key: SLACK_APP_TOKEN
+      merge: true
+- name: telegram_bot_token
+  kind: static
+  description: hermes credential for TELEGRAM_BOT_TOKEN
+  config:
+    default: null
+  targets:
+  - provider: local
+    kind: file
+    config:
+      path: /Users/zacharyloeber/.hermes/.env
+      format: dotenv
+      key: TELEGRAM_BOT_TOKEN
+      merge: true

agents/hermes/agent.env.template

@@ -0,0 +1,11 @@
+# SecretZero agent.env.template — safe to commit (no values)
+# Generated from present credentials at adopt time.
+
+# messaging: slack_app_token
+# SLACK_APP_TOKEN=
+
+# messaging: slack_bot_token
+# SLACK_BOT_TOKEN=
+
+# messaging: telegram_bot_token
+# TELEGRAM_BOT_TOKEN=

docs/index.md

@@ -53,8 +53,21 @@ SecretZero is a secrets management tool that automates the creation, seeding, an
 If you are an agent reading this project remotely through `gh`, `curl`, or a GitHub/MCP client,
 start here.
 
+**Agent runtime integration (Hermes / OpenClaw):**
+
+```bash
+export SZ_AGENT_MODE=true
+secretzero agent list --format json
+secretzero agent adopt --dry-run --format json
+secretzero agent adopt --preseed-lockfile --format json
+```
+
+See `skills/secretzero-agent-adopt/SKILL.md`. `secretzero agent backup` is an alias of `agent adopt`
+(not `secretzero backup create`).
+
 Skill files:
 
+- `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md`
 - `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md`
 - `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md`
 - `https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md`
@@ -77,6 +90,7 @@ Use that downloader like this:
 Direct Hermes install:
 
 ```bash
+hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md
@@ -230,6 +244,7 @@ secretzero agent sync --help
 If you are running Hermes Agent, install the skills directly from this repository:
 
 ```bash
+hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent-adopt/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-agent/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-author/SKILL.md
 hermes skills install https://raw.githubusercontent.com/zloeber/SecretZero/main/skills/secretzero-handle/SKILL.md

docs/user-guide/agent-adopt.md

@@ -0,0 +1,39 @@
+# Agent adopt (Hermes / OpenClaw)
+
+Bootstrap a SecretZero environment from a local agent install without exposing secret values.
+
+## Commands
+
+```bash
+secretzero agent list --format json
+secretzero agent adopt --dry-run --format json
+secretzero agent adopt --preseed-lockfile --format json
+```
+
+`secretzero agent backup` is an alias of `agent adopt`. It is **not** `secretzero backup create`.
+
+## Defaults
+
+- `--output-dir` defaults to the resolved agent install path (`~/.hermes`, `~/.openclaw`, …).
+- `--target` autodetects **Hermes**, then **OpenClaw**.
+- Only **present** catalog credentials become manifest secrets.
+
+## GitOps capture
+
+```bash
+secretzero agent adopt \
+  --target hermes \
+  --source-dir ~/.hermes \
+  --output-dir ./agents/hermes \
+  --template
+```
+
+## Restore loop
+
+1. `secretzero agent adopt --preseed-lockfile`
+2. `secretzero validate -f <Secretfile>`
+3. `secretzero agent sync --json -f <Secretfile>`
+4. `secretzero sync -f <Secretfile>`
+
+See `skills/secretzero-agent-adopt/SKILL.md` and
+`docs/superpowers/specs/2026-05-27-agent-adopt-design.md`.