Initial import of NousResearch/hermes-agent

optional-skills/software-development/code-wiki/SKILL.md

@@ -0,0 +1,445 @@
+---
+name: code-wiki
+description: "Generate wiki docs + Mermaid diagrams for any codebase."
+version: 0.1.0
+author: Teknium (teknium1), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Documentation, Mermaid, Architecture, Diagrams, Wiki, Code-Analysis]
+    related_skills: [codebase-inspection, github-repo-management]
+---
+
+# Code Wiki Skill
+
+Generate a comprehensive wiki for any codebase — overview, architecture, per-module deep-dives, Mermaid class and sequence diagrams. Inspired by Google CodeWiki, but works on local repos, private repos, and any language. Uses only existing Hermes tools (`terminal`, `read_file`, `search_files`, `write_file`); no Docker, no external services, no extra dependencies.
+
+This skill produces **reference documentation** (what/how). It does not produce strategic narrative (why — that's a different skill).
+
+## When to Use
+
+- User says "document this codebase", "generate a wiki", "make architecture diagrams"
+- Onboarding to an unfamiliar repo and wants a structured reference
+- User points at a GitHub URL and asks for documentation
+- Need a stable artifact (markdown + Mermaid) that renders on GitHub
+
+Do NOT use this for:
+- Single-file or single-function documentation — just answer directly
+- API reference for one specific endpoint — use `read_file` and answer inline
+- Strategic "why does this exist" narrative — different skill, different purpose
+- Codebases the user is actively developing in this session — just answer questions as they come
+
+## Prerequisites
+
+- No env vars required.
+- `git` on PATH for repo SHA tracking and remote clones.
+- Optional: `pygount` for language-breakdown stats (see the `codebase-inspection` skill).
+
+## How to Run
+
+Invoke through the `terminal` tool from the target repo's root, then use `read_file` / `search_files` / `write_file` to produce the wiki. Default output location is `~/.hermes/wikis/<repo-name>/`. Only write into the repo (`docs/wiki/`) when the user explicitly requests it.
+
+## Quick Reference
+
+| Step | Action |
+|---|---|
+| 1 | Resolve target — local cwd, given path, or `git clone --depth 50 <url>` to a temp dir |
+| 2 | Scan structure — `ls`, `find -maxdepth 3`, manifest files, README |
+| 3 | Pick 8–10 modules to document |
+| 4 | Write `README.md` (overview + module map) |
+| 5 | Write `architecture.md` with Mermaid flowchart |
+| 6 | Write per-module docs in `modules/` |
+| 7 | Write `diagrams/class-diagram.md` (Mermaid classDiagram) |
+| 8 | Write `diagrams/sequences.md` (Mermaid sequenceDiagram, 2–4 workflows) |
+| 9 | Write `getting-started.md` |
+| 10 | Write `api.md` if applicable, else skip |
+| 11 | Write `.codewiki-state.json` |
+| 12 | Report paths to user |
+
+## Procedure
+
+### 1. Resolve the target
+
+For a GitHub URL:
+
+```bash
+WIKI_TMP=$(mktemp -d)
+git clone --depth 50 <url> "$WIKI_TMP/repo"
+cd "$WIKI_TMP/repo"
+REPO_SHA=$(git rev-parse HEAD)
+REPO_NAME=$(basename <url> .git)
+```
+
+For a local path (or cwd if none given):
+
+```bash
+cd <path>
+REPO_SHA=$(git rev-parse HEAD 2>/dev/null || echo "uncommitted")
+REPO_NAME=$(basename "$PWD")
+```
+
+Then set the output dir:
+
+```bash
+OUTPUT_DIR="$HOME/.hermes/wikis/$REPO_NAME"
+mkdir -p "$OUTPUT_DIR/modules" "$OUTPUT_DIR/diagrams"
+```
+
+### 2. Scan repo structure
+
+Use the `terminal` tool for the shell work, `read_file` for manifests:
+
+```bash
+# Shallow tree first
+ls -la
+
+# Deeper tree, noise filtered
+find . -type d \
+  -not -path '*/\.*' \
+  -not -path '*/node_modules*' \
+  -not -path '*/venv*' \
+  -not -path '*/__pycache__*' \
+  -not -path '*/dist*' \
+  -not -path '*/build*' \
+  -not -path '*/target*' \
+  -maxdepth 3 | sort
+
+# Language breakdown (skip if pygount unavailable)
+pygount --format=summary \
+  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,target" \
+  . 2>/dev/null || true
+```
+
+Then `read_file` the relevant manifests (`package.json`, `pyproject.toml`, `setup.py`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`) and the project README. Use `search_files target='files'` to find them rather than guessing names.
+
+### 3. Pick modules to document
+
+Cap initial pass at **8–10 modules**. Heuristics by language:
+
+- Python: top-level packages (dirs with `__init__.py`), plus subsystem dirs
+- JS/TS: `src/<subdir>`, top-level workspace dirs
+- Rust: each crate in a workspace, or top-level `src/<module>` dirs
+- Go: each top-level package directory
+- Mixed/unfamiliar: top-level directories that contain source code (not config, not tests)
+
+For very large repos, prioritize by:
+1. Imported-from count (a module imported by many is core)
+2. LOC (bigger modules usually warrant their own doc)
+3. Mentions in README / top-level docs
+
+State the module list to the user before generating per-module docs on big repos — gives them a chance to redirect.
+
+### 4. Write `README.md`
+
+`read_file` the actual project README plus the top 2–3 entry-point files. Then `write_file`:
+
+````markdown
+# <Project Name>
+
+<One paragraph: what it is and what it's for. Self-contained — don't assume the
+reader has the source README.>
+
+## Key Concepts
+
+- **<Concept 1>** — <one line>
+- **<Concept 2>** — <one line>
+
+## Entry Points
+
+- [`path/to/main.py`](<link>) — <what runs when you start it>
+- [`path/to/cli.py`](<link>) — <CLI surface>
+
+## High-Level Architecture
+
+<2-3 sentences. Detail goes in architecture.md.>
+
+See [architecture.md](architecture.md).
+
+## Module Map
+
+| Module | Purpose |
+|---|---|
+| [`<module>`](modules/<module>.md) | <one-line purpose> |
+
+## Getting Started
+
+See [getting-started.md](getting-started.md).
+````
+
+For link targets in local mode use relative paths. For cloned repos use `https://github.com/<owner>/<repo>/blob/<sha>/<path>` so links survive future commits.
+
+### 5. Write `architecture.md`
+
+````markdown
+# Architecture
+
+<2-3 paragraphs: shape of the system. What talks to what. Where data enters,
+where it exits, where state lives.>
+
+## Components
+
+- **<Component>** — <1-2 sentences>. See [`modules/<module>.md`](modules/<module>.md).
+
+## System Diagram
+
+```mermaid
+flowchart TD
+    User([User]) --> Entry[Entry Point]
+    Entry --> Core[Core Engine]
+    Core --> StorageA[(Database)]
+    Core --> ExternalAPI{{External API}}
+```
+
+## Data Flow
+
+1. **<Step>** — [`<file>`](<link>)
+2. **<Step>** — [`<file>`](<link>)
+
+## Key Design Decisions
+
+- <Anything load-bearing the reader should know>
+````
+
+**Mermaid shape semantics:**
+- `[]` = component
+- `[()]` = database / storage
+- `{{}}` = external service
+- `(())` = entry point or terminal
+- `-->` = sync call, `-.->` = async/event
+
+Cap at ~20 nodes per diagram. Split into sub-diagrams if larger.
+
+### 6. Write per-module docs in `modules/`
+
+For each selected module, inspect its layout with `ls`, identify 3–5 most important files (by size, by being named `core.py` / `main.py` / `__init__.py`, by being imported a lot), then `read_file` those files (use `offset` / `limit` to read only what you need; prefer `search_files` for specific symbols).
+
+````markdown
+# Module: `<module>`
+
+<1-2 sentence purpose.>
+
+## Responsibilities
+
+- <bullet>
+- <bullet>
+
+## Key Files
+
+- [`<module>/<file>`](<link>) — <what it does>
+
+## Public API
+
+<Functions/classes/constants other code uses. Group related items. Show
+signatures, not full implementations.>
+
+## Internal Structure
+
+<How the module is organized internally. State management.>
+
+## Dependencies
+
+- **Used by:** <other modules>
+- **Uses:** <other modules + external libs>
+
+## Notable Patterns / Gotchas
+
+- <Anything non-obvious>
+````
+
+### 7. Write `diagrams/class-diagram.md`
+
+Pick the 5–10 most important classes/types. `read_file` them, then write:
+
+````markdown
+# Class Diagram
+
+## Core Types
+
+```mermaid
+classDiagram
+    class Agent {
+        +string name
+        +list~Tool~ tools
+        +chat(message) string
+    }
+    class Tool {
+        <<interface>>
+        +name string
+        +execute(args) any
+    }
+    Agent --> Tool : uses
+    Tool <|-- TerminalTool
+    Tool <|-- WebTool
+```
+
+## Notes
+
+<Anything the diagram can't express — lifecycle, threading, etc.>
+````
+
+For languages without classes (Go, C, Rust): use the diagram for struct relationships, or skip class-diagram.md and explain it in prose in architecture.md. Don't force-fit.
+
+### 8. Write `diagrams/sequences.md`
+
+Pick 2–4 of the most important workflows. Trace each call path through the code (read entry point, follow function calls), then:
+
+````markdown
+# Sequence Diagrams
+
+## Workflow: <Name>
+
+<1 sentence describing what this does and when it runs.>
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant Agent
+    participant LLM
+    User->>CLI: types message
+    CLI->>Agent: chat(message)
+    Agent->>LLM: API call
+    LLM-->>Agent: response + tool_calls
+    Agent->>Agent: execute tools
+    Agent-->>CLI: final response
+```
+
+### Walkthrough
+
+1. **User input** — [`cli.py:HermesCLI.run_session`](<link>)
+2. **Message dispatch** — [`run_agent.py:AIAgent.chat`](<link>)
+````
+
+Don't invent participants. Every box must correspond to a real component the reader can find in the code.
+
+### 9. Write `getting-started.md`
+
+````markdown
+# Getting Started
+
+## Prerequisites
+
+<From manifest files + README. Be specific — versions if pinned.>
+
+## Installation
+
+```bash
+<exact commands>
+```
+
+## First Run
+
+```bash
+<minimum command to see the system do something useful>
+```
+
+## Common Workflows
+
+### <Workflow 1>
+<commands>
+
+## Configuration
+
+- `<config-file>` — <what it controls>
+- Env var `<VAR>` — <what it controls>
+
+## Where to Go Next
+
+- Architecture: [architecture.md](architecture.md)
+- Module reference: [README.md#module-map](README.md#module-map)
+````
+
+### 10. Write `api.md` (skip if not applicable)
+
+Only write this if the project is a library or API server. If it is:
+
+- Find the public API surface (`__init__.py` exports, OpenAPI specs, route handlers, exported types)
+- Document each public entry with signature, parameters, return type, one-line description
+- Group by category
+
+### 11. Write the state file
+
+```bash
+cat > "$OUTPUT_DIR/.codewiki-state.json" <<EOF
+{
+  "repo_name": "$REPO_NAME",
+  "source_path": "$PWD",
+  "source_sha": "$REPO_SHA",
+  "generated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "generator": "hermes-agent code-wiki skill v0.1.0",
+  "modules_documented": []
+}
+EOF
+```
+
+### 12. Report to user
+
+State exactly what was generated and where:
+
+```
+Generated wiki at ~/.hermes/wikis/<repo-name>/:
+  README.md                   project overview, module map
+  architecture.md             system architecture + flowchart
+  getting-started.md          setup, first run, workflows
+  modules/<N files>           per-module deep-dives
+  diagrams/architecture.md    Mermaid flowchart
+  diagrams/class-diagram.md   Mermaid class diagram
+  diagrams/sequences.md       Mermaid sequence diagrams
+```
+
+If you cloned to a temp dir, remind the user it can be removed (`rm -rf "$WIKI_TMP"`) after they've reviewed the wiki.
+
+## Scope Control
+
+Generating a full wiki for a 500K-LOC monorepo is wildly token-expensive. Default to bounded scope:
+
+- Initial scan: max depth 3 directories
+- Per-module docs: cap at 10 modules unless user expands scope
+- Per-file reads: prefer `search_files` for symbols + `read_file` with `offset`/`limit` over full reads
+- Skip vendored code (`vendor/`, `third_party/`, generated code, `_pb2.py`, `.min.js`)
+
+If the user says "do the whole thing exhaustively", believe them — but ballpark the cost first: "this repo has ~340 source files, comprehensive coverage will be expensive — confirm?"
+
+## Re-Run / Update
+
+If `.codewiki-state.json` already exists at the target path:
+
+- Read it for previous SHA and module list
+- If source SHA matches: ask user if they want to regenerate or skip
+- If SHA differs: offer to regenerate only modules with changed files (`git diff --name-only <old-sha> HEAD`)
+
+Full incremental-regeneration is a future enhancement — for now, regenerating the whole thing is acceptable.
+
+## Pitfalls
+
+- **Fabricating components.** Every diagram node and claimed function call must be in the source. `read_file` before writing. The single biggest failure mode for auto-generated docs is plausible-sounding fabrication.
+- **Generic AI prose.** "This module is responsible for..." is content-free. Say what the module actually does in domain-specific terms.
+- **Restating code as prose.** A module doc that says "the `process` function processes things by calling `process_item` on each item" is worse than just linking to the function.
+- **Mermaid > 50 nodes.** They don't render legibly. Split them.
+- **Documenting tests, generated code, or vendored deps as if they were product code.** Skip them.
+- **In-repo output without asking.** Default is `~/.hermes/wikis/`. Only write into the repo when the user explicitly requests it.
+- **Mermaid special chars need quotes:** `A["Tool / Agent"]` not `A[Tool / Agent]`. `<br>` for line breaks inside a node.
+- **Nested code fences in SKILL.md.** When writing a markdown example that contains a Mermaid block, use 4-backtick outer fences so the 3-backtick inner ` ```mermaid ` doesn't close the outer. (This SKILL.md does it.)
+- **classDiagram generics** render as `~T~` (e.g. `List~Tool~`), not `<T>`.
+- **GitHub Mermaid theme is fixed** — don't include `%%{init: ...}%%` blocks; they're stripped on render.
+
+## Verification
+
+After writing, verify:
+
+1. **Mermaid blocks balance** — opens equal closes per file:
+   ```bash
+   for f in "$OUTPUT_DIR"/diagrams/*.md "$OUTPUT_DIR"/architecture.md; do
+     opens=$(grep -c '^```mermaid' "$f")
+     total=$(grep -c '^```' "$f")
+     echo "$f: $opens mermaid blocks, $total total fences (expect total = opens*2)"
+   done
+   ```
+2. **All expected files exist** —
+   ```bash
+   ls "$OUTPUT_DIR"/{README.md,architecture.md,getting-started.md,.codewiki-state.json} \
+      "$OUTPUT_DIR"/modules/ "$OUTPUT_DIR"/diagrams/
+   ```
+3. **Module count matches what you intended** — `ls "$OUTPUT_DIR/modules" | wc -l` should equal the number of modules you committed to in Step 3.
+4. **No fabricated paths** — sanity-check 2–3 source links resolve to real files.

optional-skills/software-development/code-wiki/templates/README.md

@@ -0,0 +1,31 @@
+# {{PROJECT_NAME}}
+
+{{ONE_PARAGRAPH_DESCRIPTION}}
+
+## Key Concepts
+
+- **{{CONCEPT_1}}** — {{ONE_LINE}}
+- **{{CONCEPT_2}}** — {{ONE_LINE}}
+- **{{CONCEPT_3}}** — {{ONE_LINE}}
+
+## Entry Points
+
+- [`{{PATH_1}}`]({{LINK_1}}) — {{WHAT_IT_DOES}}
+- [`{{PATH_2}}`]({{LINK_2}}) — {{WHAT_IT_DOES}}
+
+## High-Level Architecture
+
+{{TWO_TO_THREE_SENTENCES}}
+
+See [architecture.md](architecture.md) for the full picture.
+
+## Module Map
+
+| Module | Purpose |
+|---|---|
+| [`{{MODULE_1}}`](modules/{{MODULE_1}}.md) | {{ONE_LINE_PURPOSE}} |
+| [`{{MODULE_2}}`](modules/{{MODULE_2}}.md) | {{ONE_LINE_PURPOSE}} |
+
+## Getting Started
+
+See [getting-started.md](getting-started.md).

optional-skills/software-development/code-wiki/templates/architecture.md

@@ -0,0 +1,30 @@
+# Architecture
+
+{{TWO_TO_THREE_PARAGRAPHS_SHAPE_OF_SYSTEM}}
+
+## Components
+
+- **{{COMPONENT_1}}** — {{ONE_TO_TWO_SENTENCES}} See [`modules/{{MODULE}}.md`](modules/{{MODULE}}.md).
+- **{{COMPONENT_2}}** — {{ONE_TO_TWO_SENTENCES}}
+
+## System Diagram
+
+```mermaid
+flowchart TD
+    User([User]) --> Entry[Entry Point]
+    Entry --> Core[Core Engine]
+    Core --> StorageA[(Database)]
+    Core --> ExternalAPI{{External API}}
+```
+
+## Data Flow
+
+1. **{{STEP_1}}** — [`{{FILE}}`]({{LINK}})
+2. **{{STEP_2}}** — [`{{FILE}}`]({{LINK}})
+3. **{{STEP_3}}** — [`{{FILE}}`]({{LINK}})
+
+## Key Design Decisions
+
+- {{DECISION_1}}
+- {{DECISION_2}}
+- {{DECISION_3}}

optional-skills/software-development/code-wiki/templates/getting-started.md

@@ -0,0 +1,47 @@
+# Getting Started
+
+## Prerequisites
+
+- {{LANGUAGE_RUNTIME_VERSION}}
+- {{DEPENDENCY}}
+
+## Installation
+
+```bash
+{{INSTALL_COMMANDS}}
+```
+
+## First Run
+
+```bash
+{{FIRST_RUN_COMMAND}}
+```
+
+You should see {{EXPECTED_OUTPUT}}.
+
+## Common Workflows
+
+### {{WORKFLOW_1}}
+
+```bash
+{{COMMANDS}}
+```
+
+### {{WORKFLOW_2}}
+
+```bash
+{{COMMANDS}}
+```
+
+## Configuration
+
+Key config files and settings:
+
+- `{{CONFIG_FILE}}` — {{WHAT_IT_CONTROLS}}
+- Env var `{{VAR}}` — {{WHAT_IT_CONTROLS}}
+
+## Where to Go Next
+
+- Architecture overview: [architecture.md](architecture.md)
+- Module reference: [README.md#module-map](README.md#module-map)
+- Diagrams: [diagrams/](diagrams/)

optional-skills/software-development/code-wiki/templates/module.md

@@ -0,0 +1,38 @@
+# Module: `{{MODULE_NAME}}`
+
+{{ONE_TO_TWO_SENTENCE_PURPOSE}}
+
+## Responsibilities
+
+- {{BULLET_1}}
+- {{BULLET_2}}
+- {{BULLET_3}}
+
+## Key Files
+
+- [`{{PATH_1}}`]({{LINK_1}}) — {{WHAT_IT_DOES}}
+- [`{{PATH_2}}`]({{LINK_2}}) — {{WHAT_IT_DOES}}
+
+## Public API
+
+### `{{FUNCTION_NAME}}({{SIGNATURE}})`
+
+{{ONE_LINE_DESCRIPTION}}
+
+**Parameters:**
+- `{{PARAM}}` ({{TYPE}}) — {{DESCRIPTION}}
+
+**Returns:** {{TYPE}} — {{DESCRIPTION}}
+
+## Internal Structure
+
+{{HOW_THE_MODULE_IS_ORGANIZED}}
+
+## Dependencies
+
+- **Used by:** {{OTHER_MODULES}}
+- **Uses:** {{OTHER_MODULES_AND_LIBS}}
+
+## Notable Patterns / Gotchas
+
+- {{ANYTHING_NON_OBVIOUS}}

optional-skills/software-development/rest-graphql-debug/SKILL.md

@@ -0,0 +1,514 @@
+---
+name: rest-graphql-debug
+description: "Debug REST/GraphQL APIs: status codes, auth, schemas, repro."
+version: 1.2.0
+author: eren-karakus0
+license: MIT
+metadata:
+  hermes:
+    tags: [api, rest, graphql, http, debugging, testing, curl, integration]
+    category: software-development
+    related_skills: [systematic-debugging, test-driven-development]
+---
+
+# API Testing & Debugging
+
+Drive REST and GraphQL diagnosis through Hermes tools — `terminal` for `curl`, `execute_code` for Python `requests`, `web_extract` for vendor docs. Isolate the failing layer before guessing at the fix.
+
+## When to Use
+
+- API returns unexpected status or body
+- Auth fails (401/403 after token refresh, OAuth, API key)
+- Works in Postman but fails in code
+- Webhook / callback integration debugging
+- Building or reviewing API integration tests
+- Rate limiting or pagination issues
+
+Skip for UI rendering, DB query tuning, or DNS/firewall infra (escalate).
+
+## Core Principle
+
+**Isolate the layer, then fix.** A 200 OK can hide broken data. A 500 can mask a one-character auth typo. Walk the chain in order; never skip a step.
+
+```
+1. Connectivity   → can we reach the host at all?
+1.5 Timeouts      → connect-slow vs read-slow?
+2. TLS/SSL        → cert valid and trusted?
+3. Auth           → credentials correct and unexpired?
+4. Request format → payload shape match server expectations?
+5. Response parse → does our code accept what came back?
+6. Semantics      → does the data mean what we assume?
+```
+
+## 5-Minute Quickstart
+
+### REST via terminal
+
+```python
+# Verbose request/response exchange
+terminal('curl -v https://api.example.com/users/1')
+
+# POST with JSON
+terminal("""curl -X POST https://api.example.com/users \\
+  -H 'Content-Type: application/json' \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -d '{"name":"test","email":"test@example.com"}'""")
+
+# Headers only
+terminal('curl -sI https://api.example.com/health')
+
+# Pretty-print JSON
+terminal('curl -s https://api.example.com/users | python3 -m json.tool')
+```
+
+### GraphQL via terminal
+
+```python
+terminal("""curl -X POST https://api.example.com/graphql \\
+  -H 'Content-Type: application/json' \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -d '{"query":"{ user(id: 1) { name email } }"}'""")
+```
+
+**GraphQL gotcha:** servers often return HTTP 200 even when the query failed. Always inspect the `errors` field regardless of status code:
+
+```python
+execute_code('''
+import os, requests
+resp = requests.post(
+    "https://api.example.com/graphql",
+    json={"query": "{ user(id: 1) { name email } }"},
+    headers={"Authorization": f"Bearer {os.environ['TOKEN']}"},
+    timeout=10,
+)
+data = resp.json()
+if data.get("errors"):
+    for err in data["errors"]:
+        print(f"GraphQL error: {err['message']} (path: {err.get('path')})")
+print(data.get("data"))
+''')
+```
+
+### Python (requests) via execute_code
+
+```python
+execute_code('''
+import requests
+resp = requests.get(
+    "https://api.example.com/users/1",
+    headers={"Authorization": "Bearer <TOKEN>"},
+    timeout=(3.05, 30),  # (connect, read)
+)
+print(resp.status_code, dict(resp.headers))
+print(resp.text[:500])
+''')
+```
+
+## Layered Debug Flow
+
+### Step 1 — Connectivity
+
+```python
+terminal('nslookup api.example.com')
+terminal('curl -v --connect-timeout 5 https://api.example.com/health')
+```
+
+Failures: DNS not resolving, firewall, VPN required, proxy missing.
+
+### Step 1.5 — Timeouts
+
+Distinguish *can't reach* from *reaches but slow*:
+
+```python
+terminal('''curl -w "dns:%{time_namelookup}s connect:%{time_connect}s tls:%{time_appconnect}s ttfb:%{time_starttransfer}s total:%{time_total}s\\n" \\
+  -o /dev/null -s https://api.example.com/endpoint''')
+```
+
+In Python, always pass a tuple timeout — `requests` has no default and will hang forever:
+
+```python
+execute_code('''
+import requests
+from requests.exceptions import ConnectTimeout, ReadTimeout
+try:
+    requests.get(url, timeout=(3.05, 30))
+except ConnectTimeout:
+    print("Cannot reach host — DNS, firewall, VPN")
+except ReadTimeout:
+    print("Connected but server is slow")
+''')
+```
+
+Diagnosis: high `time_connect` is network/firewall; high `time_starttransfer` with low `time_connect` is a slow server.
+
+### Step 2 — TLS/SSL
+
+```python
+terminal('curl -vI https://api.example.com 2>&1 | grep -E "SSL|subject|expire|issuer"')
+```
+
+Failures: expired cert, self-signed, hostname mismatch, missing CA bundle. Use `-k` only for ad-hoc debug, never in code.
+
+### Step 3 — Authentication
+
+```python
+# Token validity check
+terminal('curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $TOKEN" https://api.example.com/me')
+
+# Decode JWT exp claim — handles base64url padding correctly
+execute_code('''
+import json, base64, os
+tok = os.environ["TOKEN"]
+payload = tok.split(".")[1]
+payload += "=" * (-len(payload) % 4)
+print(json.dumps(json.loads(base64.urlsafe_b64decode(payload)), indent=2))
+''')
+```
+
+Checklist:
+- Token expired? (`exp` claim in JWT)
+- Right scheme? Bearer vs Basic vs Token vs `X-Api-Key`
+- Right environment? Staging key on prod is a classic
+- API key in header vs query param (`?api_key=…`)?
+
+### Step 4 — Request Format
+
+```python
+terminal("""curl -v -X POST https://api.example.com/endpoint \\
+  -H 'Content-Type: application/json' \\
+  -d '{"key":"value"}' 2>&1""")
+```
+
+**Content-Type / body mismatch — the silent 415/400:**
+
+```python
+# WRONG — data= sends form-encoded, header lies
+requests.post(url, data='{"k":"v"}', headers={"Content-Type": "application/json"})
+
+# RIGHT — json= auto-sets header AND serializes
+requests.post(url, json={"k": "v"})
+
+# WRONG — Accept says XML, code calls .json()
+requests.get(url, headers={"Accept": "text/xml"})
+
+# RIGHT — let requests build multipart with boundary
+requests.post(url, files={"file": open("doc.pdf", "rb")})
+```
+
+Common: form-encoded vs JSON, missing required fields, wrong HTTP method, unencoded query params.
+
+### Step 5 — Response Parsing
+
+Always inspect content-type before calling `.json()`:
+
+```python
+execute_code('''
+import requests
+resp = requests.post(url, json=payload, timeout=10)
+print(f"status={resp.status_code}")
+print(f"headers={dict(resp.headers)}")
+ct = resp.headers.get("Content-Type", "")
+if "application/json" in ct:
+    print(resp.json())
+else:
+    print(f"unexpected content-type {ct!r}, body={resp.text[:500]!r}")
+''')
+```
+
+Failures: HTML error page where JSON expected, empty body, wrong charset.
+
+### Step 6 — Semantic Validation
+
+Parsed cleanly — but is the data *correct*?
+
+- Does `"status": "active"` mean what your code thinks?
+- ID in response matches the one requested?
+- Timestamps in expected timezone?
+- Pagination returning all results, or just page 1?
+
+## HTTP Status Playbook
+
+### 401 Unauthorized — credentials missing or invalid
+
+1. `Authorization` header actually present? (`curl -v` to confirm)
+2. Token correct and unexpired?
+3. Right auth scheme? (`Bearer` vs `Basic` vs `Token`)
+4. Some APIs use query param (`?api_key=…`) instead of header.
+
+### 403 Forbidden — authenticated but not authorized
+
+1. Token has the required scopes/permissions?
+2. Resource owned by a different account?
+3. IP allowlist blocking you?
+4. CORS in browser? (check `Access-Control-Allow-Origin`)
+
+### 404 Not Found — resource doesn't exist or URL is wrong
+
+1. Path correct? (trailing slash, typo, version prefix)
+2. Resource ID exists?
+3. Right API version (`/v1/` vs `/v2/`)?
+4. Right base URL (staging vs prod)?
+
+### 409 Conflict — state collision
+
+1. Resource already exists (duplicate create)?
+2. Stale `ETag` / `If-Match`?
+3. Concurrent modification by another process?
+
+### 422 Unprocessable Entity — valid JSON, invalid data
+
+The error body usually names the bad fields. Check:
+- Field types (string vs int, date format)
+- Required vs optional
+- Enum values inside the allowed set
+
+### 429 Too Many Requests — rate limited
+
+Check `Retry-After` and `X-RateLimit-*` headers. Exponential backoff:
+
+```python
+execute_code('''
+import time, requests
+
+def with_backoff(method, url, **kwargs):
+    for attempt in range(5):
+        resp = requests.request(method, url, **kwargs)
+        if resp.status_code != 429:
+            return resp
+        wait = int(resp.headers.get("Retry-After", 2 ** attempt))
+        time.sleep(wait)
+    return resp
+''')
+```
+
+### 5xx — server-side, usually not your fault
+
+- **500** — server bug. Capture correlation ID, file with provider.
+- **502** — upstream down. Backoff + retry.
+- **503** — overloaded / maintenance. Check status page.
+- **504** — upstream timeout. Reduce payload or raise timeout.
+
+For all 5xx: backoff with jitter, alert on persistence.
+
+## Pagination & Idempotency
+
+**Pagination.** Verify you're getting *all* results. Look for `next_cursor`, `next_page`, `total_count`. Two patterns:
+- Offset (`?limit=100&offset=200`) — simple, can skip items if data shifts.
+- Cursor (`?cursor=abc123`) — preferred for live or large datasets.
+
+**Idempotency.** For non-idempotent operations (POST), send `Idempotency-Key: <uuid>` so retries don't double-charge / double-create. Mandatory for payments and orders.
+
+## Contract Validation
+
+Catch schema drift before it hits production:
+
+```python
+execute_code('''
+import requests
+
+def validate_user(data: dict) -> list[str]:
+    errors = []
+    required = {"id": int, "email": str, "created_at": str}
+    for field, expected in required.items():
+        if field not in data:
+            errors.append(f"missing field: {field}")
+        elif not isinstance(data[field], expected):
+            errors.append(f"{field}: want {expected.__name__}, got {type(data[field]).__name__}")
+    return errors
+
+resp = requests.get(f"{BASE}/users/1", headers=HEADERS, timeout=10)
+issues = validate_user(resp.json())
+if issues:
+    print(f"contract violations: {issues}")
+''')
+```
+
+Run after API upgrades, when integrating new third parties, or in CI smoke tests.
+
+## Correlation IDs
+
+Always capture the provider's request ID — fastest path to vendor support:
+
+```python
+execute_code('''
+import requests
+resp = requests.post(url, json=payload, headers=headers, timeout=10)
+request_id = (
+    resp.headers.get("X-Request-Id")
+    or resp.headers.get("X-Trace-Id")
+    or resp.headers.get("CF-Ray")  # Cloudflare
+)
+if resp.status_code >= 400:
+    print(f"failed status={resp.status_code} req_id={request_id} ts={resp.headers.get('Date')}")
+''')
+```
+
+**Vendor bug-report template:**
+
+```
+Endpoint:    POST /api/v1/orders
+Request ID:  req_abc123xyz
+Timestamp:   2026-03-17T14:30:00Z
+Status:      500
+Expected:    201 with order object
+Actual:      500 {"error":"internal server error"}
+Repro:       curl -X POST … (auth: <REDACTED>)
+```
+
+## Regression Test Template
+
+Drop this into `tests/` and run via `terminal('pytest tests/test_api_smoke.py -v')`:
+
+```python
+import os, requests, pytest
+
+BASE_URL = os.environ.get("API_BASE_URL", "https://api.example.com")
+TOKEN    = os.environ.get("API_TOKEN", "")
+HEADERS  = {"Authorization": f"Bearer {TOKEN}"}
+
+class TestAPISmoke:
+    def test_health(self):
+        resp = requests.get(f"{BASE_URL}/health", timeout=5)
+        assert resp.status_code == 200
+
+    def test_list_users_returns_array(self):
+        resp = requests.get(f"{BASE_URL}/users", headers=HEADERS, timeout=10)
+        assert resp.status_code == 200
+        data = resp.json()
+        assert isinstance(data.get("data", data), list)
+
+    def test_get_user_required_fields(self):
+        resp = requests.get(f"{BASE_URL}/users/1", headers=HEADERS, timeout=10)
+        assert resp.status_code in (200, 404)
+        if resp.status_code == 200:
+            user = resp.json()
+            assert "id" in user and "email" in user
+
+    def test_invalid_auth_returns_401(self):
+        resp = requests.get(
+            f"{BASE_URL}/users",
+            headers={"Authorization": "Bearer invalid-token"},
+            timeout=10,
+        )
+        assert resp.status_code == 401
+```
+
+## Security
+
+### Token handling
+- Never log full tokens. Redact: `Bearer <REDACTED>`.
+- Never hardcode tokens in scripts. Read from env (`os.environ["API_TOKEN"]`) or `~/.hermes/.env`.
+- Rotate immediately if a token surfaces in logs, error messages, or git history.
+
+### Safe logging
+
+```python
+def redact_auth(headers: dict) -> dict:
+    sensitive = {"authorization", "x-api-key", "cookie", "set-cookie"}
+    return {k: ("<REDACTED>" if k.lower() in sensitive else v) for k, v in headers.items()}
+```
+
+### Leak checklist
+
+- [ ] **Credentials in URLs.** API keys in query strings end up in server logs, browser history, referrer headers — use headers.
+- [ ] **PII in error responses.** `404 on /users/123` shouldn't reveal whether the user exists (enumeration).
+- [ ] **Stack traces in prod.** 500s shouldn't leak file paths, framework versions.
+- [ ] **Internal hostnames/IPs.** `10.x.x.x`, `internal-api.corp.local` in error bodies.
+- [ ] **Tokens echoed back.** Some APIs include the auth token in error details. Verify they don't.
+- [ ] **Verbose `Server` / `X-Powered-By`.** Stack-info leaks. Note for security review.
+
+## Hermes Tool Patterns
+
+### terminal — for curl, dig, openssl
+
+```python
+terminal('curl -sI https://api.example.com')
+terminal('openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null | openssl x509 -noout -dates')
+```
+
+### execute_code — for multi-step Python flows
+
+When debugging spans auth → fetch → paginate → validate, use `execute_code`. Variables persist for the script, results print to stdout, no risk of token spam in your context:
+
+```python
+execute_code('''
+import os, requests
+
+token = os.environ["API_TOKEN"]
+base  = "https://api.example.com"
+H     = {"Authorization": f"Bearer {token}"}
+
+# 1. auth
+me = requests.get(f"{base}/me", headers=H, timeout=10)
+print(f"auth {me.status_code}")
+
+# 2. paginate
+all_users, cursor = [], None
+while True:
+    params = {"cursor": cursor} if cursor else {}
+    r = requests.get(f"{base}/users", headers=H, params=params, timeout=10)
+    body = r.json()
+    all_users.extend(body["data"])
+    cursor = body.get("next_cursor")
+    if not cursor:
+        break
+print(f"users={len(all_users)}")
+''')
+```
+
+### web_extract — for vendor API docs
+
+Pull the spec for the endpoint you're debugging instead of guessing:
+
+```python
+web_extract(urls=["https://docs.example.com/api/v1/users"])
+```
+
+### delegate_task — for full CRUD test sweeps
+
+```python
+delegate_task(
+    goal="Test all CRUD endpoints for /api/v1/users",
+    context="""
+Follow the rest-graphql-debug skill (optional-skills/software-development/rest-graphql-debug).
+Base URL: https://api.example.com
+Auth: Bearer token from API_TOKEN env var.
+
+For each verb (POST, GET, PATCH, DELETE):
+  - happy path: assert status + response schema
+  - error cases: 400, 404, 422
+  - log a repro curl for any failure (redact tokens)
+
+Output: pass/fail per endpoint + correlation IDs for failures.
+""",
+    toolsets=["terminal", "file"],
+)
+```
+
+## Output Format
+
+When reporting findings:
+
+```
+## Finding
+Endpoint: POST /api/v1/users
+Status:   422 Unprocessable Entity
+Req ID:   req_abc123xyz
+
+## Repro
+curl -X POST https://api.example.com/api/v1/users \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <REDACTED>' \
+  -d '{"name":"test"}'
+
+## Root Cause
+Missing required field `email`. Server validation rejects before processing.
+
+## Fix
+-d '{"name":"test","email":"test@example.com"}'
+```
+
+## Related
+
+- `systematic-debugging` — once the failing API layer is isolated, root-cause your code
+- `test-driven-development` — write the regression test before shipping the fix