zloeber · zloeber · Jun 5, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.claude/skills/gitnexus/gitnexus-cli/SKILL.md b/.claude/skills/gitnexus/gitnexus-cli/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-cli
 description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+metadata:
+  internal: true
 ---
 
 # GitNexus CLI Commands

diff --git a/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md b/.claude/skills/gitnexus/gitnexus-debugging/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-debugging
 description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+metadata:
+  internal: true
 ---
 
 # Debugging with GitNexus

diff --git a/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md b/.claude/skills/gitnexus/gitnexus-exploring/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-exploring
 description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+metadata:
+  internal: true
 ---
 
 # Exploring Codebases with GitNexus

diff --git a/.claude/skills/gitnexus/gitnexus-guide/SKILL.md b/.claude/skills/gitnexus/gitnexus-guide/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-guide
 description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+metadata:
+  internal: true
 ---
 
 # GitNexus Guide

diff --git a/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md b/.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-impact-analysis
 description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+metadata:
+  internal: true
 ---
 
 # Impact Analysis with GitNexus

diff --git a/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md b/.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-refactoring
 description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+metadata:
+  internal: true
 ---
 
 # Refactoring with GitNexus

diff --git a/.cursor/skills/gitnexus/gitnexus-cli/SKILL.md b/.cursor/skills/gitnexus/gitnexus-cli/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-cli
 description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
+metadata:
+  internal: true
 ---
 
 # GitNexus CLI Commands

diff --git a/.cursor/skills/gitnexus/gitnexus-debugging/SKILL.md b/.cursor/skills/gitnexus/gitnexus-debugging/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-debugging
 description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
+metadata:
+  internal: true
 ---
 
 # Debugging with GitNexus

diff --git a/.cursor/skills/gitnexus/gitnexus-exploring/SKILL.md b/.cursor/skills/gitnexus/gitnexus-exploring/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-exploring
 description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
+metadata:
+  internal: true
 ---
 
 # Exploring Codebases with GitNexus

diff --git a/.cursor/skills/gitnexus/gitnexus-guide/SKILL.md b/.cursor/skills/gitnexus/gitnexus-guide/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-guide
 description: "Use when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: \"What GitNexus tools are available?\", \"How do I use GitNexus?\""
+metadata:
+  internal: true
 ---
 
 # GitNexus Guide

diff --git a/.cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md b/.cursor/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-impact-analysis
 description: "Use when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: \"Is it safe to change X?\", \"What depends on this?\", \"What will break?\""
+metadata:
+  internal: true
 ---
 
 # Impact Analysis with GitNexus

diff --git a/.cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md b/.cursor/skills/gitnexus/gitnexus-refactoring/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: gitnexus-refactoring
 description: "Use when the user wants to rename, extract, split, move, or restructure code safely. Examples: \"Rename this function\", \"Extract this into a module\", \"Refactor this class\", \"Move this to a separate file\""
+metadata:
+  internal: true
 ---
 
 # Refactoring with GitNexus

diff --git a/.cursor/skills/ui-ux-pro-max/SKILL.md b/.cursor/skills/ui-ux-pro-max/SKILL.md
@@ -1,3 +1,10 @@
+---
+name: ui-ux-pro-max
+description: Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations.
+metadata:
+  internal: true
+---
+
 # ui-ux-pro-max
 
 Comprehensive design guide for web and mobile applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 13 technology stacks. Searchable database with priority-based recommendations.

diff --git a/.cursorrules b/.cursorrules
@@ -12,6 +12,7 @@ A secrets-as-code management tool that validates, generates, syncs, and tracks p
 ## Non-Negotiables
 - Never commit plaintext secrets, API keys, or credentials.
 - Never log or persist secret values outside approved providers/targets and lockfile metadata hashes.
+- **Agents:** never consume secrets in context — use SecretZero only (`skills/secretzero/SKILL.md` absolute rule).
 - Use Pydantic v2 APIs only (`model_dump()` / `model_dump_json()`), not v1 methods.
 - Use Rich console output for CLI UX (`Console.print()`), not raw `print`.
 - Register new provider/generator/target capabilities through bundle manifests and the bundle registry.
@@ -44,6 +45,8 @@ At the end of any coding task, run a fast local gate:
 ./scripts/agent.pre-commit.sh --mode fast --quiet
 ```
 
+The gate includes `task docs:links` (lychee on `README.md` and `docs/`). After doc edits, you can run `task docs:links` alone for a quick check.
+
 Before any push/merge, run the full gate:
 
 ```bash

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -31,9 +31,14 @@ jobs:
         run: |
           uv sync --frozen --all-extras
 
-      - name: Export Secretfile schema for docs
-        run: |
-          uv run secretzero schema export --output docs/Secretfile.schema.json
+      - name: Install lychee
+        run: bash ./scripts/ci-install-lychee.sh
+
+      - name: Check README.md and docs/ hyperlinks
+        run: lychee --config lychee.toml README.md docs/
+
+      - name: Export Secretfile schema for MkDocs
+        run: uv run secretzero schema export --output docs/Secretfile.schema.json
 
       - name: Build docs
         run: |

diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -14,6 +14,18 @@ permissions:
   contents: read
 
 jobs:
+  docs-links:
+    name: Docs hyperlink check (lychee)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install lychee
+        run: bash ./scripts/ci-install-lychee.sh
+
+      - name: Check README.md and docs/
+        run: lychee --config lychee.toml README.md docs/
+
   schema-doc-parity:
     name: Schema/Docs Parity
     runs-on: ubuntu-latest

diff --git a/.mex/ROUTER.md b/.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-27
+last_updated: 2026-06-05
 ---
 
 # Session Bootstrap
@@ -54,7 +54,9 @@ 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), `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).
+- **Agent absolute rule (skills):** `skills/secretzero/SKILL.md` — never consume secrets in LLM/tool context; use SecretZero only for discovery, authoring, seeding, sync, and human entry (`web` / `agent sync --web`). All focused skills inherit this rule.
+- **Agent skill guidance split:** SecretZero guidance is now split into focused skills — `skills/secretzero-author/SKILL.md` (schema-compliant Secretfile authoring, **guided session** with manifest-root confirmation, inventory table, add/edit loop with generator/target menus, optional `detect`/`discover`, optional background `secretzero web`, Hermes + MCP guidance, `.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).
+- **Internal vs public skills:** Only `skills/**/SKILL.md` files are published for remote install (Hermes/raw URLs). All other repo `SKILL.md` files (`.cursor/skills/**`, `.claude/skills/**`) must include `metadata: internal: true` in frontmatter.
 - **`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.
@@ -67,6 +69,7 @@ Then read this file fully before doing anything else in this session.
   - **Ansible Vault extension:** existing `ansible_vault` provider now exposes target kind **`ansible_vault_file`** so encrypted vault files participate directly in target dispatch.
 - **Auto-generated provider bundle reference docs:** `scripts/generate_provider_bundle_docs.py` now emits `docs/reference/provider-bundles-auto.md` from the live `BundleRegistry`; wired into `task docs:build` / `task docs:serve` via `task docs:generate:provider-bundles`.
 - **FAQ clarification for encrypted-in-git lanes:** `docs/reference/faq.md` now explains that SOPS/git-crypt/Ansible Vault workflows are target-layer encrypted repository adapters; the true secret-zero trust anchor remains the bootstrap credential/key material used to unlock them.
+- **Docs hyperlink gate:** `task docs:links` runs lychee on `README.md` and `docs/` (`lychee.toml`); wired into `scripts/agent.pre-commit.sh`, `.pre-commit-config.yaml`, and GitHub Actions (`test.yaml` job `docs-links`, `docs.yaml` pre-build). See `.mex/patterns/docs-links-lychee.md`.
 - **Public onboarding docs now front-load remote agent skill install paths:** `README.md` and `docs/index.md` both include an early **Agent Quick Start** with raw `SKILL.md` URLs, Hermes direct install commands, and a raw-download helper script (`scripts/download-secretzero-skills.zsh`) for copying both skill folders into `./skills` / `~/.agents/skills` / Hermes `external_dirs`.
 - **Structured secret hashing:** Lockfile hashing now accepts non-string secret payloads (e.g. JSON objects for multi-field static secrets) via canonical JSON normalization before SHA-256, preventing `'dict' object has no attribute 'encode'` during sync.
 - **Example manifest:** `examples/azure-appreg-to-aws-sm.yml` uses a structured static `value` map with YAML `null` leaves so interactive `secretzero sync` prompts once per missing field (sorted keys); `.szvar` / `--var-file` can pre-fill those leaves to skip prompts.
@@ -82,7 +85,7 @@ Then read this file fully before doing anything else in this session.
 - **CLI version subcommand:** Added `secretzero version` with `--detailed` runtime metadata and `--format` output selection (`text`, `json`, `yaml`) for both human and agent-friendly version reporting.
 - **CLI status compact mode:** Default `secretzero status` text output is now a compact color-coded secret→target mapping; prior full status report moved to `secretzero status --detailed` (`--verbose` implies `--detailed`).
 - **CLI status/provider readiness + clean command:** Compact status now uses provider connectivity preflight in addition to identity to classify unsynced targets (local/file no longer misclassified as unknown when connectivity succeeds). Added `secretzero clean` for lockfile orphan cleanup without running sync (`--dry-run`, `--format text|json`).
-- **Supply-chain hardening defaults:** CI/workflows now install `uv` via SHA-pinned `astral-sh/setup-uv`, use frozen dependency resolution (`uv sync --frozen ...`) in release/test/docs/agent pre-commit paths, pin PyPI publish action to a specific commit SHA, avoid mutable `wrangler@latest` installs in docs publishing, and keep `tool.uv.override-dependencies` floors current for pip-audit (including `langsmith>=0.8.0` for CVE-2026-45134 and `starlette>=1.0.1` for PYSEC-2026-161).
+- **Supply-chain hardening defaults:** CI/workflows now install `uv` via SHA-pinned `astral-sh/setup-uv`, use frozen dependency resolution (`uv sync --frozen ...`) in release/test/docs/agent pre-commit paths, pin PyPI publish action to a specific commit SHA, avoid mutable `wrangler@latest` installs in docs publishing, and keep `tool.uv.override-dependencies` floors current for pip-audit (including `pip>=26.1.2` for PYSEC-2026-196, `langsmith>=0.8.0` for CVE-2026-45134, and `starlette>=1.0.1` for PYSEC-2026-161).
 - **Schema/docs parity guardrail:** Any Secretfile-facing model/config change must follow `.mex/patterns/schema-doc-parity.md` to keep `task schema:update`, `docs/schema.md`, `docs/user-guide/configuration/index.md`, tests, and example manifests in sync.
 - **Lockfile state parity guardrail:** Sync-state evaluation (`synced`/`pending`/`drift`) must be implemented once in `src/secretzero/lockfile_state.py` and reused by dashboard/graph/CLI render layers; do not duplicate target-hash fallback logic in UI code.
 

diff --git a/.mex/context/setup.md b/.mex/context/setup.md
@@ -52,7 +52,8 @@ last_updated: 2026-04-10
 - `secretzero sync` — perform generation/sync and update lockfile.
 - `task lint:fix && task format && task schema:update` — local quality + schema maintenance.
 - `task test && task security:scan && task test:validations` — full verification pipeline. `task security:scan` syncs the frozen `--all-extras` environment before auditing dependencies/code.
-- `task pre-commit` — install and run local pre-commit hooks; the repo hook now runs `task security:scan`.
+- `task pre-commit` — install and run local pre-commit hooks; hooks run `task security:scan` and `task docs:links` (lychee on `README.md` + `docs/`).
+- `task docs:links` — check hyperlinks in `README.md` and `docs/` (requires `lychee` via `mise install`).
 
 ## Common Issues
 **Unknown generator/target/provider kind:** ensure bundle registration path exists and provider extras are installed.  

diff --git a/.mex/patterns/INDEX.md b/.mex/patterns/INDEX.md
@@ -14,6 +14,7 @@ Lookup table for all pattern files in this directory. Check here before starting
 | [aws-json-target-format.md](aws-json-target-format.md) | Changing AWS `ssm_parameter` / `secrets_manager` structured JSON target behavior or docs |
 | [backup-cli-workflow.md](backup-cli-workflow.md) | Changing `secretzero backup create` / `backup restore` defaults, encryption mode, or environment fan-out |
 | [docs-entrypoint-parity.md](docs-entrypoint-parity.md) | Updating `README.md` and `docs/index.md` together for install/onboarding/agent-skill guidance |
+| [docs-links-lychee.md](docs-links-lychee.md) | `task docs:links` / lychee config for README and `docs/` hyperlink checks |
 | [gitnexus-metagit-integration.md](gitnexus-metagit-integration.md) | GitNexus `secrets_overlay`, MetaGit registry, discovery bindings, blast-radius CLI |
 | [debug-sync.md](debug-sync.md) | Diagnosing sync failures across config/provider/generator/target boundaries |
 | [file-target-tfvars.md](file-target-tfvars.md) | Local `file` target `format: tfvars` for Terraform `.tfvars` assignment files |

diff --git a/.mex/patterns/docs-links-lychee.md b/.mex/patterns/docs-links-lychee.md
@@ -0,0 +1,38 @@
+---
+name: docs-links-lychee
+description: Validate hyperlinks in README.md and docs/ with lychee.
+triggers:
+  - "broken link"
+  - "lychee"
+  - "docs:links"
+last_updated: 2026-06-04
+---
+
+# Docs hyperlink check (lychee)
+
+## Command
+
+```bash
+task docs:links
+```
+
+`docs/schema.md` links to committed `../Secretfile.schema.json` (not gitignored `docs/Secretfile.schema.json`). CI may still run `scripts/ci-prepare-docs-links.sh` to materialize the MkDocs copy. Then scans `README.md` and `docs/` using `lychee.toml`.
+
+## When it runs
+
+- **CI:** `.github/workflows/test.yaml` job `docs-links` (every push/PR); `.github/workflows/docs.yaml` before MkDocs build on `main`
+- End of agent work: `./scripts/agent.pre-commit.sh` (fast and full)
+- Pre-commit hook: `secretzero-docs-links` in `.pre-commit-config.yaml`
+- After editing docs or README
+
+## Fixing failures
+
+1. Prefer fixing the URL (404/410) or pointing to `https://secret0.com` / `https://github.com/zloeber/SecretZero/issues` instead of disabled GitHub Discussions.
+2. For intentional non-checkable URLs (localhost docs, placeholders, CI-blocked hosts like `kubernetes.io`), add a regex to `lychee.toml` `exclude` — do not disable the task.
+3. `kubernetes.io` links are valid but often fail lychee on GitHub Actions with "connection failed"; they remain excluded until upstream egress is reliable.
+4. Install tool: `mise install` (see `mise.toml` `lychee` tool).
+5. CI installs via `scripts/ci-install-lychee.sh` (handles v0.24+ nested release tarballs).
+
+## Example manifest links
+
+Jenkins CI example manifest: `examples/multi-cicd.yml` (not `jenkins-credentials.yml`).