@sentry/warden 0.35.1 → 0.36.0

package/skills/warden/SOURCES.md

@@ -1,39 +0,0 @@
-# Warden Skill Sources
-
-## Source Inventory
-
-| Source | Trust tier | Confidence | Usage constraints |
-|--------|------------|------------|-------------------|
-| `skills/warden/SKILL.md` | canonical runtime | high | Keep concise; runtime instructions only. |
-| `skills/warden/references/*.md` | bundled runtime references | high | Keep focused by lookup need. |
-| `packages/warden/src/cli/` | implementation | high | Verify CLI flags and behavior here before changing examples. |
-| `packages/warden/src/config/` and `packages/warden/src/types/` | implementation | high | Verify config field names, defaults, and validation rules here. |
-| `packages/docs/src/pages/cli.astro` | generated/user docs source | medium | Useful for CLI descriptions, but implementation wins on conflicts. |
-| `packages/docs/src/pages/config.astro` | generated/user docs source | medium | Useful for config examples, but implementation wins on conflicts. |
-| `packages/docs/src/pages/skill.astro` | generated/user docs source | medium | Useful for install and skill-discovery language. |
-
-## Coverage Matrix
-
-| Dimension | Coverage status | Evidence |
-|-----------|-----------------|----------|
-| CLI surface | covered | `references/cli-reference.md` lists commands, targets, flags, exit codes, and examples. |
-| Config/runtime options | covered | `references/configuration.md` and `references/config-schema.md` cover `warden.toml` structure, fields, defaults, triggers, and environment variables. |
-| Common use cases | covered | `SKILL.md` covers run-before-commit, explicit skill runs, file targets, git refs, fix mode, and config edits. |
-| Known issues/workarounds | partial | `references/configuration.md` has troubleshooting; CLI auth and install failures could use more detail. |
-| Version/migration variance | partial | Remote skill pinning and cache behavior are documented; package-version migration notes are not maintained here. |
-
-## Decisions
-
-- Keep `SKILL.md` as a quick router because agents often need only a command, not the full CLI documentation.
-- Keep CLI, config, schema, and skill creation in separate references so agents can load only the relevant detail.
-- Keep Warden-specific skill creation guidance in this skill even though generic skill authoring belongs elsewhere, because Warden has its own discovery, config, and remote-skill behavior.
-
-## Open Gaps
-
-- Add or verify an auth/setup troubleshooting reference if repeated agent runs fail before Warden can execute.
-- Confirm CLI examples after each release that changes flags, output modes, or init/add/sync behavior.
-- Add migration notes if Warden introduces breaking config changes beyond `version = 1`.
-
-## Changelog
-
-- 2026-04-27: Reverse-engineered maintenance spec and source inventory from the distributed `warden` skill.

package/skills/warden/SPEC.md

@@ -1,112 +0,0 @@
-# Warden Skill Specification
-
-## Intent
-
-The `warden` skill teaches coding agents how to run Warden during local development, interpret its output, and update Warden configuration or skill definitions when asked.
-
-It exists as the lightweight runtime companion to the Warden CLI. The skill should get agents to the right command or reference quickly without duplicating the full product documentation.
-
-## Scope
-
-In scope:
-
-- Running Warden against uncommitted changes, explicit files, or git refs.
-- Reading and editing `warden.toml`.
-- Explaining Warden CLI flags, exit codes, severity thresholds, and output modes.
-- Creating or wiring local Warden analysis skills.
-- Directing agents to focused bundled references for detailed CLI, config, and skill-authoring behavior.
-
-Out of scope:
-
-- Replacing Warden product documentation.
-- Running full-repository batch sweeps; use `warden-sweep` for that workflow.
-- Defining project-specific review policy.
-- Teaching generic agent skill authoring beyond Warden-specific discovery and config.
-
-## Users And Trigger Context
-
-- Primary users: coding agents working in repositories that use Warden.
-- Common user requests: "run warden", "check my changes", "review before commit", "update warden.toml", "add a Warden trigger", "create a Warden skill".
-- Should not trigger for: ordinary code review requests with no Warden context, generic testing, PR writing, or full-repository sweep requests.
-
-## Runtime Contract
-
-- Required first actions:
-  - Identify whether the user wants to run Warden, edit config, inspect output, or create/update a Warden skill.
-  - Load only the reference needed for that task.
-  - Prefer local repository configuration over generic examples.
-- Required outputs:
-  - For runs: summarize command used, findings count, failure threshold, and next action.
-  - For config edits: state the changed trigger or setting and how to validate it.
-  - For skill creation: state where the skill was created and how it is referenced.
-- Non-negotiable constraints:
-  - Do not loop Warden repeatedly on unchanged work.
-  - Do not invent config fields; check `references/config-schema.md` for exact names.
-  - Do not treat Warden findings as advisory text to suppress; fix the code or explicitly explain why a finding is not actionable.
-- Expected bundled files loaded at runtime:
-  - `references/cli-reference.md`
-  - `references/configuration.md`
-  - `references/config-schema.md`
-  - `references/creating-skills.md`
-
-## Source And Evidence Model
-
-Authoritative sources:
-
-- Warden CLI behavior in `src/cli/`.
-- Warden config loading and schemas in `src/config/` and `src/types/`.
-- Documentation pages in `packages/docs/src/pages/`.
-- Existing runtime references in `skills/warden/references/`.
-
-Useful improvement sources:
-
-- positive examples: agent sessions where Warden was run once, findings were fixed, and config edits used valid schema fields
-- negative examples: repeated Warden reruns with no changes, invented config fields, stale CLI flags, or generic skill instructions that do not match Warden discovery
-- commit logs/changelogs: CLI flag changes, config schema changes, and skill discovery changes
-- issue or PR feedback: reports of confusing Warden setup, missing command coverage, or stale agent skill docs
-- eval results: local prompts covering run, config, output interpretation, and skill creation paths
-
-Data that must not be stored:
-
-- secrets, tokens, or API keys
-- customer data
-- private repository URLs or identifiers not needed for reproduction
-- raw Warden logs containing sensitive code or findings
-
-## Reference Architecture
-
-- `SKILL.md` contains task routing, quick commands, core constraints, and the reference map.
-- `SOURCES.md` contains source inventory, coverage, gaps, and changelog.
-- `references/` contains focused CLI, config, schema, and Warden skill creation guides.
-- `references/evidence/` is unused until repeated examples need durable storage.
-- `scripts/` is unused; this skill delegates execution to the installed `warden` CLI.
-- `assets/` is unused.
-
-## Evaluation
-
-- Lightweight validation:
-  - Run the skill validator against `skills/warden`.
-  - Check that every referenced bundled file exists.
-  - Spot-check CLI flags and config fields against source or generated docs.
-- Deeper evaluation:
-  - Exercise prompts for running Warden, adding a trigger, explaining output, and creating a skill.
-- Holdout examples:
-  - Preserve only redacted examples if recurring failures appear.
-- Acceptance gates:
-  - `SKILL.md` stays concise and routes to focused references.
-  - Long references include navigation.
-  - Config examples use valid field names.
-  - Trigger description catches Warden-specific local development tasks without matching generic code review.
-
-## Known Limitations
-
-- The skill assumes the `warden` CLI is installed and authenticated where required.
-- CLI and config details can drift when source changes without updating the bundled references.
-- Some host agents expose different skill-root variables; references are written as bundled file paths, while examples may need host-specific substitution.
-
-## Maintenance Notes
-
-- Update `SKILL.md` when task routing, trigger language, or universal run constraints change.
-- Update `SOURCES.md` when source inventory, decisions, coverage, or gaps change.
-- Update references when CLI flags, config fields, remote skill behavior, or examples change.
-- Update `references/evidence/` only for durable positive or negative examples that should guide future iterations.

package/skills/warden/references/cli-reference.md

@@ -1,149 +0,0 @@
-# CLI Reference
-
-## Contents
-
-- Usage
-- Commands
-- Targets
-- Options
-- Per-Command Options
-- Severity Levels
-- Exit Codes
-- Examples
-
-## Usage
-
-```
-warden [command] [targets...] [options]
-```
-
-## Commands
-
-| Command | Description |
-|---------|-------------|
-| `(default)` | Run analysis on targets or using warden.toml skills |
-| `init` | Initialize warden.toml and GitHub workflow |
-| `add [skill]` | Add a skill to warden.toml |
-| `sync [remote]` | Update cached remote skills to latest |
-| `setup-app` | Create a GitHub App for Warden via manifest flow |
-
-## Targets
-
-| Target | Description |
-|--------|-------------|
-| `<files>` | Analyze specific files (e.g., `src/auth.ts`) |
-| `<glob>` | Analyze files matching pattern (e.g., `"src/**/*.ts"`) |
-| `<git-ref>` | Analyze changes from git ref (e.g., `HEAD~3`, `main..feature`) |
-| `(none)` | Analyze uncommitted changes using warden.toml skills |
-
-Ambiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use `--git` to force git ref interpretation.
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--skill <name>` | Run only this skill by name or path; names fall back to built-ins |
-| `--config-path <path>` | Path to warden.toml or a directory containing it (default: `./warden.toml`). `--config` is a deprecated alias. |
-| `-m, --model <model>` | Model to use (fallback when not set in config) |
-| `--json` | Output results as JSON |
-| `-o, --output <path>` | Write full run output to a JSONL file |
-| `--fail-on <severity>` | Exit with code 1 if findings >= severity |
-| `--report-on <severity>` | Only show findings >= severity in output |
-| `--fix` | Automatically apply all suggested fixes |
-| `--parallel <n>` | Max concurrent skill executions (default: 4) |
-| `--git` | Force ambiguous targets to be treated as git refs |
-| `--offline` | Use cached remote skills without network access |
-| `-q, --quiet` | Errors and final summary only |
-| `-v, --verbose` | Show real-time findings and hunk details |
-| `-vv` | Show debug info (token counts, latencies) |
-| `--debug` | Enable debug output (equivalent to `-vv`) |
-| `--log` | Use log output (no animations, timestamped) |
-| `--color / --no-color` | Override color detection |
-| `-h, --help` | Show help message |
-| `-V, --version` | Show version number |
-
-## Per-Command Options
-
-**Init:**
-| Option | Description |
-|--------|-------------|
-| `-f, --force` | Overwrite existing files |
-
-**Add:**
-| Option | Description |
-|--------|-------------|
-| `--list` | List available skills |
-| `--remote <ref>` | Remote repository (`owner/repo`, URL, or with `@sha`) |
-| `--force` | Bypass skill cache and fetch latest |
-
-**Sync:**
-| Option | Description |
-|--------|-------------|
-| `--remote <ref>` | Specific remote to sync (default: all) |
-
-**Setup-app:**
-| Option | Description |
-|--------|-------------|
-| `--org <name>` | Create under organization (default: personal) |
-| `--port <number>` | Local server port (default: 3000) |
-| `--timeout <sec>` | Callback timeout in seconds (default: 300) |
-| `--name <string>` | Custom app name (default: Warden) |
-| `--no-open` | Print URL instead of opening browser |
-
-## Severity Levels
-
-| Level | Meaning |
-|-------|---------|
-| `high` | Must fix before merge |
-| `medium` | Worth reviewing |
-| `low` | Minor improvement |
-| `off` | Disable the threshold |
-
-## Exit Codes
-
-| Code | Meaning |
-|------|---------|
-| `0` | No findings at or above `--fail-on` threshold |
-| `1` | Findings at or above `--fail-on` threshold |
-
-## Examples
-
-```bash
-# Initialize
-warden init
-
-# Interactive skill selection
-warden add
-warden add security-review
-warden add --list
-
-# Remote skills
-warden add --remote <org>/<repo> --skill <skill-name>
-warden add --remote https://github.com/<org>/<repo> --skill <skill-name>
-warden add --remote <org>/<repo>@<ref> --skill <skill-name>
-
-# Run analysis
-warden                                  # Skills from warden.toml
-warden src/auth.ts                      # Specific file
-warden src/auth.ts --skill <skill-name>
-warden "src/**/*.ts"                    # Glob pattern
-warden HEAD~3                           # Git changes
-warden HEAD~3 --skill <skill-name>
-warden main..HEAD                       # Branch diff
-
-# Output control
-warden --json
-warden --fail-on high
-warden -o results.jsonl
-
-# Fix mode
-warden --fix
-
-# Cached skills only
-warden --offline
-warden sync                             # Update all unpinned remote skills
-
-# GitHub App setup
-warden setup-app
-warden setup-app --org myorg
-```

package/skills/warden/references/config-schema.md

@@ -1,141 +0,0 @@
-# warden.toml Configuration Schema
-
-## Contents
-
-- Top-Level Structure
-- Defaults Section
-- Skills Section
-- Severity Values
-- Built-in Skip Patterns
-- Environment Variables
-
-## Top-Level Structure
-
-```toml
-version = 1                    # Required, must be 1
-
-[defaults]                     # Optional, inherited by all skills
-[defaults.agent]               # Optional, default analysis runtime settings
-[defaults.auxiliary]           # Optional, default helper model settings
-[defaults.synthesis]           # Optional, default synthesis model settings
-[[skills]]                     # Required, array of skill configs
-```
-
-## Defaults Section
-
-```toml
-[defaults]
-runtime = "pi"                        # Default runtime
-model = "openai/gpt-5.5"              # Legacy default analysis model
-maxTurns = 50                         # Legacy default analysis turns
-defaultBranch = "main"                # Base branch for comparisons
-failOn = "high"                       # Exit 1 if findings >= this severity
-reportOn = "medium"                   # Show findings >= this severity
-maxFindings = 50                      # Max findings to report (0 = unlimited)
-reportOnSuccess = false               # Post report even with no findings
-ignorePaths = ["*.test.ts"]           # Exclude matching files
-
-[defaults.agent]
-model = "openai/gpt-5.5"              # Default repo-aware analysis model
-maxTurns = 50                         # Max agentic turns per hunk
-reasoningEffort = "medium"            # off | low | medium | high | xhigh
-
-[defaults.auxiliary]
-model = "anthropic/claude-haiku-4-5"  # Helper model for extraction and fix gates
-maxRetries = 5                        # Retries for auxiliary structured calls
-
-[defaults.synthesis]
-model = "anthropic/claude-opus-4-5"   # Consolidation and generated-skill build model
-
-[defaults.chunking]
-enabled = true                 # Enable hunk-based chunking
-
-[defaults.chunking.coalesce]
-enabled = true                 # Merge nearby hunks
-maxGapLines = 30               # Lines between hunks to merge
-maxChunkSize = 8000            # Max chars per chunk
-
-[[defaults.chunking.filePatterns]]
-pattern = "*.config.*"         # Glob pattern
-mode = "whole-file"            # per-hunk | whole-file | skip
-```
-
-`[defaults.agent].reasoningEffort` controls repo-aware skill reasoning across runtimes. When omitted, each runtime uses its own default.
-
-`[defaults.synthesis].model` falls back to `[defaults.auxiliary].model` when omitted. Legacy `[defaults].model` and `[defaults].maxTurns` are still supported as analysis fallbacks.
-
-## Skills Section
-
-```toml
-[[skills]]
-name = "skill-name"            # Required, unique identifier
-remote = "owner/repo@sha"      # Optional, fetch skill from GitHub repo
-paths = ["src/**"]             # Include only matching files
-ignorePaths = ["**/*.test.ts"] # Exclude matching files
-
-# Optional overrides (inherit from defaults if not set)
-model = "anthropic/claude-opus-4-5"
-maxTurns = 100
-failOn = "high"
-reportOn = "medium"
-maxFindings = 20
-reportOnSuccess = true
-
-[[skills.triggers]]
-type = "pull_request"          # Required: pull_request | local | schedule
-actions = ["opened", "synchronize"]  # Required for pull_request
-
-# Schedule-specific (only for type = "schedule")
-[[skills.triggers]]
-type = "schedule"
-
-[skills.triggers.schedule]
-issueTitle = "Daily Security Review"   # GitHub issue title for tracking
-createFixPR = true                     # Create PR with fixes
-fixBranchPrefix = "security-fix"       # Branch name prefix
-```
-
-**Trigger types:**
-- `pull_request` - Triggers on PR events
-- `local` - Local CLI only (will not run in CI)
-- `schedule` - Cron schedule (GitHub Action only)
-
-All skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use `type = "local"` for skills that should *only* run locally.
-
-**Actions (for pull_request):**
-- `opened`, `synchronize`, `reopened`, `closed`
-
-## Severity Values
-
-Used in `failOn` and `reportOn`:
-- `high` - Must fix before merge
-- `medium` - Worth reviewing
-- `low` - Minor improvement
-- `off` - Disable threshold
-
-## Built-in Skip Patterns
-
-Always skipped (cannot be overridden):
-- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.
-- Minified files: `**/*.min.js`, `**/*.min.css`
-- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`
-- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `WARDEN_MODEL` | Default model (lowest priority) |
-| `WARDEN_OPENAI_API_KEY` | OpenAI API key for OpenAI Pi models |
-| `WARDEN_ANTHROPIC_API_KEY` | Anthropic API key for Anthropic Pi models or Claude runtime |
-| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |
-| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |
-
-## Model Precedence (highest to lowest)
-
-1. Skill-level `model`
-2. `[defaults.agent]` `model`
-3. `[defaults]` `model` (legacy fallback)
-4. CLI `--model` flag
-5. `WARDEN_MODEL` env var
-6. SDK default

package/skills/warden/references/configuration.md

@@ -1,143 +0,0 @@
-# Configuration (warden.toml)
-
-## Contents
-
-- Minimal Example
-- Skill Configuration
-- Common Patterns
-- Model Lanes
-- Model Precedence
-- Environment Variables
-- Troubleshooting
-
-See [config-schema.md](config-schema.md) for the complete schema reference.
-
-## Minimal Example
-
-The `name` field references a skill you've created (via `warden add`) or defined in `.agents/skills/<name>/SKILL.md`. Use that same name everywhere — in config, CLI flags, and triggers.
-
-```toml
-version = 1
-
-[defaults.agent]
-model = "openai/gpt-5.5"
-reasoningEffort = "medium"
-
-[[skills]]
-name = "my-skill"           # matches .agents/skills/my-skill/SKILL.md
-paths = ["src/**/*.ts"]
-
-[[skills.triggers]]
-type = "pull_request"
-actions = ["opened", "synchronize"]
-```
-
-## Skill Configuration
-
-Skills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.
-
-```toml
-[[skills]]
-name = "my-skill"
-paths = ["src/auth/**", "src/payments/**"]
-failOn = "high"
-reportOn = "medium"
-maxFindings = 20
-
-[[skills.triggers]]
-type = "pull_request"
-actions = ["opened", "synchronize"]
-```
-
-**Trigger types:** `pull_request`, `local` (local-only), `schedule` (CI-only)
-
-**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`
-
-## Common Patterns
-
-**Strict checks on critical files:**
-```toml
-[[skills]]
-name = "my-skill"
-model = "anthropic/claude-opus-4-5"
-maxTurns = 100
-paths = ["src/auth/**", "src/payments/**"]
-failOn = "high"
-
-[[skills.triggers]]
-type = "pull_request"
-actions = ["opened", "synchronize"]
-```
-
-**Skip test files:**
-```toml
-[[skills]]
-name = "my-skill"
-paths = ["src/**/*.ts"]
-ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]
-```
-
-**Whole-file analysis for configs:**
-```toml
-[[defaults.chunking.filePatterns]]
-pattern = "*.config.*"
-mode = "whole-file"
-```
-
-## Model Lanes
-
-Warden uses different model lanes for different kinds of work:
-
-- Analysis: repo-aware skill execution uses `[[skills]].model`, then `[defaults.agent].model`, then legacy `[defaults].model`
-- Auxiliary: structured helper calls use `[defaults.auxiliary].model`
-- Synthesis: post-analysis consolidation and generated-skill builds use `[defaults.synthesis].model`
-
-If `[defaults.synthesis].model` is omitted, synthesis falls back to `[defaults.auxiliary].model`.
-
-`[defaults.agent].reasoningEffort` optionally controls repo-aware skill reasoning across runtimes. Supported values are `off`, `low`, `medium`, `high`, and `xhigh`. When omitted, each runtime uses its own default.
-
-## Model Precedence
-
-From highest to lowest priority:
-
-1. Skill-level `model`
-2. `[defaults.agent]` `model`
-3. `[defaults]` `model` (legacy fallback)
-4. CLI `--model` flag
-5. `WARDEN_MODEL` env var
-6. SDK default
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `WARDEN_MODEL` | Default model (lowest priority) |
-| `WARDEN_{PROVIDER}_API_KEY` | API key for the named Pi provider (e.g. `WARDEN_OPENAI_API_KEY`, `WARDEN_FIREWORKS_API_KEY`). Mirrored to the native `{PROVIDER}_API_KEY` at runtime. |
-| `WARDEN_OPENAI_API_KEY` | OpenAI API key for OpenAI Pi models |
-| `WARDEN_ANTHROPIC_API_KEY` | Anthropic API key for Anthropic Pi models or Claude runtime |
-| `WARDEN_FIREWORKS_API_KEY` | Fireworks API key for Fireworks Pi models |
-| `WARDEN_GROQ_API_KEY` | Groq API key for Groq Pi models |
-| `WARDEN_OPENROUTER_API_KEY` | OpenRouter API key for OpenRouter Pi models |
-| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |
-| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |
-
-Native provider env vars (e.g. `OPENAI_API_KEY`) also work. The `WARDEN_`-prefixed forms are
-preferred in CI so they do not collide with locally-set provider keys.
-
-## Troubleshooting
-
-**No findings reported:**
-- Check `--report-on` threshold (default shows all)
-- Verify skill matches file types in `paths`
-- Use `-v` to see which files are being analyzed
-
-**Files being skipped:**
-- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`
-- Check `ignorePaths` in config
-- Use `-vv` to see skip reasons
-
-**Token/cost issues:**
-- Reduce `maxTurns` (default: 50)
-- Lower `[defaults.agent].reasoningEffort` when the runtime supports cheaper reasoning levels
-- Use chunking settings to control chunk size
-- Filter to relevant files with `paths`

package/skills/warden/references/creating-skills.md

@@ -1,87 +0,0 @@
-# Creating Skills
-
-Skills are markdown files that tell Warden what to look for. They follow the [agentskills.io](https://agentskills.io) specification.
-
-## Skill Discovery
-
-Warden searches these directories in order (first match wins):
-
-```
-.warden/skills/{name}/SKILL.md   # Warden-local generated skills
-.agents/skills/{name}/SKILL.md   # Primary (recommended)
-.claude/skills/{name}/SKILL.md   # Backup (Claude Code convention)
-```
-
-If no repo-local skill matches, names fall back to Warden's built-in skills such as `security-review`.
-
-## SKILL.md Format
-
-```markdown
----
-name: my-skill
-description: What this skill analyzes
-allowed-tools: Read Grep Glob
----
-
-[Analysis instructions for the agent]
-
-## What to Look For
-- Specific issue type 1
-- Specific issue type 2
-
-## Output Format
-Report findings with severity, location, and suggested fix.
-```
-
-## Available Tools
-
-`Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`
-
-Most review skills only need `Read`, `Grep`, and `Glob` for exploring context.
-
-## Writing Checklist
-
-- One skill, one concern ("security review" not "code quality")
-- Clear criteria for what counts as an issue and at what severity
-- Actionable findings that include how to fix
-- Examples of good and bad code where helpful
-
-## Remote Skills
-
-Skills can be fetched from GitHub repositories:
-
-```bash
-# Add a remote skill
-warden add --remote <org>/<repo> --skill <skill-name>
-
-# Add with version pinning (recommended for reproducibility)
-warden add --remote <org>/<repo>@<ref> --skill <skill-name>
-
-# List skills in a remote repo
-warden add --remote <org>/<repo> --list
-
-# Update all unpinned remote skills
-warden sync
-
-# Update specific repo
-warden sync <org>/<repo>
-
-# Run with cached skills only (no network)
-warden --offline
-```
-
-**Remote skill in warden.toml:**
-
-```toml
-[[skills]]
-name = "my-skill"
-remote = "<org>/<repo>@<ref>"
-
-[[skills.triggers]]
-type = "pull_request"
-actions = ["opened", "synchronize"]
-```
-
-**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)
-
-**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)