@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/prismer-hermes-agent/references/native-mcp.md

@@ -0,0 +1,351 @@
+# Native MCP Client
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.
+
+## When to Use
+
+Use this whenever you want to:
+- Connect to MCP servers and use their tools from within Hermes Agent
+- Add external capabilities (filesystem access, GitHub, databases, APIs) via MCP
+- Run local stdio-based MCP servers (npx, uvx, or any command)
+- Connect to remote HTTP/StreamableHTTP MCP servers
+- Have MCP tools auto-discovered and available in every conversation
+
+For ad-hoc, one-off MCP tool calls from the terminal without configuring anything, see the `mcporter` skill instead.
+
+## Prerequisites
+
+- **mcp Python package** -- optional dependency; install with `pip install mcp`. If not installed, MCP support is silently disabled.
+- **Node.js** -- required for `npx`-based MCP servers (most community servers)
+- **uv** -- required for `uvx`-based MCP servers (Python-based servers)
+
+Install the MCP SDK:
+
+```bash
+pip install mcp
+# or, if using uv:
+uv pip install mcp
+```
+
+## Quick Start
+
+Add MCP servers to `~/.hermes/config.yaml` under the `mcp_servers` key:
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+Restart Hermes Agent. On startup it will:
+1. Connect to the server
+2. Discover available tools
+3. Register them with the prefix `mcp_time_*`
+4. Inject them into all platform toolsets
+
+You can then use the tools naturally -- just ask the agent to get the current time.
+
+## Configuration Reference
+
+Each entry under `mcp_servers` is a server name mapped to its config. There are two transport types: **stdio** (command-based) and **HTTP** (url-based).
+
+### Stdio Transport (command + args)
+
+```yaml
+mcp_servers:
+  server_name:
+    command: "npx"             # (required) executable to run
+    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
+    env:                       # (optional) environment variables for the subprocess
+      SOME_API_KEY: "value"
+    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
+    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
+```
+
+### HTTP Transport (url)
+
+```yaml
+mcp_servers:
+  server_name:
+    url: "https://my-server.example.com/mcp"   # (required) server URL
+    headers:                                     # (optional) HTTP headers
+      Authorization: "Bearer sk-..."
+    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
+    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
+```
+
+### All Config Options
+
+| Option            | Type   | Default | Description                                       |
+|-------------------|--------|---------|---------------------------------------------------|
+| `command`         | string | --      | Executable to run (stdio transport, required)     |
+| `args`            | list   | `[]`    | Arguments passed to the command                   |
+| `env`             | dict   | `{}`    | Extra environment variables for the subprocess    |
+| `url`             | string | --      | Server URL (HTTP transport, required)             |
+| `headers`         | dict   | `{}`    | HTTP headers sent with every request              |
+| `timeout`         | int    | `120`   | Per-tool-call timeout in seconds                  |
+| `connect_timeout` | int    | `60`    | Timeout for initial connection and discovery      |
+
+Note: A server config must have either `command` (stdio) or `url` (HTTP), not both.
+
+## How It Works
+
+### Startup Discovery
+
+When Hermes Agent starts, `discover_mcp_tools()` is called during tool initialization:
+
+1. Reads `mcp_servers` from `~/.hermes/config.yaml`
+2. For each server, spawns a connection in a dedicated background event loop
+3. Initializes the MCP session and calls `list_tools()` to discover available tools
+4. Registers each tool in the Hermes tool registry
+
+### Tool Naming Convention
+
+MCP tools are registered with the naming pattern:
+
+```
+mcp_{server_name}_{tool_name}
+```
+
+Hyphens and dots in names are replaced with underscores for LLM API compatibility.
+
+Examples:
+- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
+- Server `github`, tool `list-issues` → `mcp_github_list_issues`
+- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`
+
+### Auto-Injection
+
+After discovery, MCP tools are automatically injected into all `hermes-*` platform toolsets (CLI, Discord, Telegram, etc.). This means MCP tools are available in every conversation without any additional configuration.
+
+### Connection Lifecycle
+
+- Each server runs as a long-lived asyncio Task in a background daemon thread
+- Connections persist for the lifetime of the agent process
+- If a connection drops, automatic reconnection with exponential backoff kicks in (up to 5 retries, max 60s backoff)
+- On agent shutdown, all connections are gracefully closed
+
+### Idempotency
+
+`discover_mcp_tools()` is idempotent -- calling it multiple times only connects to servers that aren't already connected. Failed servers are retried on subsequent calls.
+
+## Transport Types
+
+### Stdio Transport
+
+The most common transport. Hermes launches the MCP server as a subprocess and communicates over stdin/stdout.
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
+```
+
+The subprocess inherits a **filtered** environment (see Security section below) plus any variables you specify in `env`.
+
+### HTTP / StreamableHTTP Transport
+
+For remote or shared MCP servers. Requires the `mcp` package to include HTTP client support (`mcp.client.streamable_http`).
+
+```yaml
+mcp_servers:
+  remote_api:
+    url: "https://mcp.example.com/mcp"
+    headers:
+      Authorization: "Bearer sk-..."
+```
+
+If HTTP support is not available in your installed `mcp` version, the server will fail with an ImportError and other servers will continue normally.
+
+## Security
+
+### Environment Variable Filtering
+
+For stdio servers, Hermes does NOT pass your full shell environment to MCP subprocesses. Only safe baseline variables are inherited:
+
+- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
+- Any `XDG_*` variables
+
+All other environment variables (API keys, tokens, secrets) are excluded unless you explicitly add them via the `env` config key. This prevents accidental credential leakage to untrusted MCP servers.
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      # Only this token is passed to the subprocess
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
+```
+
+### Credential Stripping in Error Messages
+
+If an MCP tool call fails, any credential-like patterns in the error message are automatically redacted before being shown to the LLM. This covers:
+
+- GitHub PATs (`ghp_...`)
+- OpenAI-style keys (`sk-...`)
+- Bearer tokens
+- Generic `token=`, `key=`, `API_KEY=`, `password=`, `secret=` patterns
+
+## Troubleshooting
+
+### "MCP SDK not available -- skipping MCP tool discovery"
+
+The `mcp` Python package is not installed. Install it:
+
+```bash
+pip install mcp
+```
+
+### "No MCP servers configured"
+
+No `mcp_servers` key in `~/.hermes/config.yaml`, or it's empty. Add at least one server.
+
+### "Failed to connect to MCP server 'X'"
+
+Common causes:
+- **Command not found**: The `command` binary isn't on PATH. Ensure `npx`, `uvx`, or the relevant command is installed.
+- **Package not found**: For npx servers, the npm package may not exist or may need `-y` in args to auto-install.
+- **Timeout**: The server took too long to start. Increase `connect_timeout`.
+- **Port conflict**: For HTTP servers, the URL may be unreachable.
+
+### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
+
+Your `mcp` package version doesn't include HTTP client support. Upgrade:
+
+```bash
+pip install --upgrade mcp
+```
+
+### Tools not appearing
+
+- Check that the server is listed under `mcp_servers` (not `mcp` or `servers`)
+- Ensure the YAML indentation is correct
+- Look at Hermes Agent startup logs for connection messages
+- Tool names are prefixed with `mcp_{server}_{tool}` -- look for that pattern
+
+### Connection keeps dropping
+
+The client retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the server is fundamentally unreachable, it gives up after 5 attempts. Check the server process and network connectivity.
+
+## Examples
+
+### Time Server (uvx)
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+Registers tools like `mcp_time_get_current_time`.
+
+### Filesystem Server (npx)
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
+    timeout: 30
+```
+
+Registers tools like `mcp_filesystem_read_file`, `mcp_filesystem_write_file`, `mcp_filesystem_list_directory`.
+
+### GitHub Server with Authentication
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+    timeout: 60
+```
+
+Registers tools like `mcp_github_list_issues`, `mcp_github_create_pull_request`, etc.
+
+### Remote HTTP Server
+
+```yaml
+mcp_servers:
+  company_api:
+    url: "https://mcp.mycompany.com/v1/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+      X-Team-Id: "engineering"
+    timeout: 180
+    connect_timeout: 30
+```
+
+### Multiple Servers
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
+
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+
+  company_api:
+    url: "https://mcp.internal.company.com/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+    timeout: 300
+```
+
+All tools from all servers are registered and available simultaneously. Each server's tools are prefixed with its name to avoid collisions.
+
+## Sampling (Server-Initiated LLM Requests)
+
+Hermes supports MCP's `sampling/createMessage` capability — MCP servers can request LLM completions through the agent during tool execution. This enables agent-in-the-loop workflows (data analysis, content generation, decision-making).
+
+Sampling is **enabled by default**. Configure per server:
+
+```yaml
+mcp_servers:
+  my_server:
+    command: "npx"
+    args: ["-y", "my-mcp-server"]
+    sampling:
+      enabled: true           # default: true
+      model: "gemini-3-flash" # model override (optional)
+      max_tokens_cap: 4096    # max tokens per request
+      timeout: 30             # LLM call timeout (seconds)
+      max_rpm: 10             # max requests per minute
+      allowed_models: []      # model whitelist (empty = all)
+      max_tool_rounds: 5      # tool loop limit (0 = disable)
+      log_level: "info"       # audit verbosity
+```
+
+Servers can also include `tools` in sampling requests for multi-turn tool-augmented workflows. The `max_tool_rounds` config prevents infinite tool loops. Per-server audit metrics (requests, errors, tokens, tool use count) are tracked via `get_mcp_status()`.
+
+Disable sampling for untrusted servers with `sampling: { enabled: false }`.
+
+## Notes
+
+- MCP tools are called synchronously from the agent's perspective but run asynchronously on a dedicated background event loop
+- Tool results are returned as JSON with either `{"result": "..."}` or `{"error": "..."}`
+- The native MCP client is independent of `mcporter` -- you can use both simultaneously
+- Server connections are persistent and shared across all conversations in the same agent process
+- Reload behavior is version-dependent. The audited slash catalog includes /reload-mcp; verify actual deployed support and active-session effects before use. Do not restart user sessions implicitly.

package/built-in-skills/prismer-hermes-agent/references/petdex.md

@@ -0,0 +1,82 @@
+# Petdex — Animated Pet Mascots
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Browse, install, and select animated "pet" mascots from the public
+[petdex](https://github.com/crafter-station/petdex) gallery. An installed pet
+reacts to agent activity (idle, running a tool, reviewing, error, done) across
+the Hermes CLI, TUI, and desktop app. This skill drives the `hermes pets` CLI
+and the `display.pet` config — it does not generate sprites.
+
+## When to Use
+
+- The user wants a desktop/terminal mascot or asks about "pets" / petdex.
+- The user wants to change, preview, or disable the active pet.
+- Diagnosing why a pet isn't showing (terminal graphics support, config).
+
+## Prerequisites
+
+- Network access to `petdex.dev` for the gallery/manifest (read-only, no auth).
+- Pillow (a core Hermes dependency) for sprite decoding — already installed.
+- For full-fidelity terminal rendering: a graphics-capable terminal (kitty,
+  Ghostty, WezTerm, iTerm2, or sixel). Otherwise a truecolor Unicode
+  half-block fallback is used automatically.
+
+## How to Run
+
+Use the `terminal` tool to run `hermes pets <subcommand>`.
+
+## Quick Reference
+
+| Goal | Command |
+| --- | --- |
+| Browse the gallery | `hermes pets list` (add a substring to filter: `hermes pets list cat`) |
+| List installed pets | `hermes pets list --installed` |
+| Install a pet | `hermes pets install <slug>` (add `--select` to make it active) |
+| Set the active pet | `hermes pets select <slug>` (omit slug for a picker) |
+| Resize the pet everywhere | `hermes pets scale <factor>` (e.g. `0.5`, clamped 0.1–3.0) |
+| Preview/animate in terminal | `hermes pets show [slug] [--cycle] [--state run]` |
+| Disable the pet | `hermes pets off` |
+| Remove a pet | `hermes pets remove <slug>` |
+| Diagnose setup | `hermes pets doctor` |
+
+## Procedure
+
+1. Find a pet: `hermes pets list <query>` and note its `slug`.
+2. Install + activate: `hermes pets install <slug> --select`.
+3. Preview it: `hermes pets show` (Ctrl+C to stop).
+4. Confirm setup: `hermes pets doctor` — shows the resolved pet, configured
+   render mode, detected terminal graphics protocol, and effective mode.
+
+Pets install into `<HERMES_HOME>/pets/<slug>/` (profile-aware). Selecting a pet
+writes `display.pet.slug` + `display.pet.enabled` to `config.yaml`.
+
+## Configuration
+
+Under `display.pet` in `config.yaml`:
+
+- `enabled` (bool) — master on/off.
+- `slug` (str) — active pet; empty = first installed.
+- `render_mode` — `auto` (detect) | `kitty` | `iterm` | `sixel` | `unicode` | `off`.
+- `scale` (float) — on-screen size of the native 192×208 frames (default 0.33,
+  clamped 0.1–3.0). One knob resizes every surface; set it with
+  `hermes pets scale <factor>`, the `/pet scale` slash command, or the desktop
+  Appearance slider.
+- `unicode_cols` (int) — width in columns for the Unicode fallback.
+
+## Pitfalls
+
+- A pet only shows once one is installed AND selected (`enabled: true`).
+- Inside a pipe/redirect (no TTY) terminal rendering is disabled by design.
+- The petdex npm CLI installs to `~/.codex/pets`; Hermes uses its own
+  profile-scoped `<HERMES_HOME>/pets/` instead — install through `hermes pets`.
+
+## Verification
+
+- `hermes pets doctor` reports `✓ ready` when a pet is installed, selected,
+  enabled, and Pillow is importable.

package/built-in-skills/prismer-hermes-agent/references/portal-auth-for-third-party-apps.md

@@ -0,0 +1,135 @@
+# Nous Portal — authenticating third-party apps against the subscription
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Recurring user question: "Can app X (Karakeep, OpenWebUI, LibreChat, OpenViking,
+LangChain pipeline, n8n flow, etc.) use my Nous Portal subscription without me
+copy-pasting an API key — ideally via the Portal login I already have?"
+
+The honest answer has three architectural layers people conflate. Walk through
+them in order before proposing solutions.
+
+---
+
+## Layer 1 — Is this thing a Hermes plugin, or a separate app?
+
+This is the question to answer FIRST. The "OpenViking" case in particular
+trips agents up.
+
+| Surface | What it actually is | Auth path |
+|---|---|---|
+| **OpenViking memory plugin** (`plugins/memory/openviking/`) | Code that runs **inside the Hermes process**. Its LLM calls go through Hermes's already-configured provider. | Already uses Portal if user's Hermes is configured for Portal. Nothing extra needed. `OPENVIKING_API_KEY` is the OpenViking *server's* own auth, not LLM auth. |
+| **OpenViking the standalone server** (separate container) | A separate context-DB service. If it ever calls an LLM on its own, that's a separate HTTP client. | Same as any external app — Layer 2/3 below. |
+| **Karakeep, n8n, LibreChat, OpenWebUI, any self-hosted app** | Different process, often different machine. Makes its own HTTPS calls to `inference-api.nousresearch.com`. | Layer 2/3 below. |
+
+**Pitfall to avoid**: do not pitch "OAuth into Portal" as the solution for a
+plugin that already runs inside Hermes. That LLM call is already authenticated
+via Hermes's provider config. The plugin's own server auth (e.g.
+`OPENVIKING_API_KEY` for talking to the OpenViking REST API) is unrelated to
+Portal.
+
+---
+
+## Layer 2 — For genuinely external apps, what does Portal actually expose?
+
+Portal at `https://inference-api.nousresearch.com/v1` is an OpenAI-compatible
+inference endpoint. It accepts **bearer-token authentication only**: either
+
+1. **A static API key** from `portal.nousresearch.com → API Keys`, or
+2. **An x402-protocol payment header** (Solana USDC, beta, anonymous, per-request).
+
+There is **no general OAuth 2.0 authorization server**. There is no
+"Sign in with Nous Portal" SSO that third-party apps can register as clients
+against. There is no shared cookie or session that browser-Portal-login
+extends to other apps on the same machine.
+
+What Hermes Agent has that *feels* like OAuth — `hermes login --provider nous`
+opening a browser, user signs in, token lands in `~/.hermes/auth.json` — is a
+**Hermes-specific browser flow**. Under the hood it produces a credential
+Hermes uses as a bearer. It is not a public OAuth provider that Karakeep et al.
+can implement a client for, because it isn't an OAuth provider at all from the
+outside.
+
+---
+
+## Layer 3 — Can we bridge the gap without Portal changing anything?
+
+For a standalone upstream integration, the conceptual pattern is a **local credential-broker proxy**. Prismer already owns this boundary in Runtime; do not instantiate the following design as a skill side effect. Even without a public
+OAuth flow, an app on the user's machine can:
+
+1. Have the authorized Runtime credential owner provision a scoped credential; do not read shared auth.json from a skill.
+2. Expose a local OpenAI-compatible endpoint at `http://localhost:NNNN/v1`.
+3. Forward incoming requests to `inference-api.nousresearch.com/v1` with that
+   bearer attached.
+
+Karakeep/OpenWebUI/etc. then point at `http://localhost:NNNN/v1` with any
+placeholder key. The user never copies their Portal key around — the proxy
+rides on the credential Hermes already holds.
+
+Where this could live in Hermes:
+
+- `gateway/platforms/api_server.py` is the precedent — it exposes the agent
+  over a local OpenAI-compatible endpoint, but routes through the full agent
+  loop (tool calls and all). The proxy variant is **pure inference
+  pass-through**: no agent loop, no tools, just forward `/chat/completions`
+  upstream with the user's stored Portal bearer.
+- ~150 lines as a new gateway adapter or a plugin under `plugins/`.
+- Token refresh: if the browser-OAuth flow produces a refreshable token, the
+  credential pool's refresh logic already exists. If it's a long-lived static
+  bearer, even simpler.
+
+This is genuinely useful and worth shipping — it's the answer to "use my
+Portal sub with $external_app without copy-pasting keys."
+
+---
+
+## Real OAuth provider on Portal — when is it worth pitching?
+
+Only when the consumer is *another first-party Nous thing* (a future SDK, a
+Nous-branded extension, a Discord-bot integration that needs per-user
+delegation, etc.). Pitching it as the answer to "use my Portal sub with
+Karakeep" is selling the user a thing that won't reach them: even if Portal
+shipped OAuth tomorrow, Karakeep's LLM-provider config UI is `base_url +
+bearer_token` with no OAuth client, no callback handler, no token refresh.
+The OpenAI ecosystem standardized on static bearers and downstream apps
+won't rebuild their config UX to accommodate a new auth flow.
+
+The features that would actually help users today, and that Portal could ship
+without depending on third-party app changes:
+
+- **Scoped, named, revocable API keys** with last-used timestamps. Same UX
+  benefits people want from OAuth (revoke a compromised key, see what's using
+  the sub, scope a key to specific models), in a shape every existing app
+  already supports.
+- **Per-key rate limits** so a noisy app can be capped without eating the
+  user's headroom for Hermes itself.
+
+---
+
+## Talking-points cheatsheet (for next time)
+
+When the user asks "can $APP use my Portal subscription":
+
+1. First decide: Hermes plugin (runs inside Hermes) or separate app? If plugin,
+   it already uses Portal via Hermes's provider config — done.
+2. If separate app: today, paste the static API key from Portal → API Keys.
+   Base URL `https://inference-api.nousresearch.com/v1`. Rate limits are
+   subscription-tier based, applied per-key.
+3. If the user pushes back with "but I don't want to paste a key" — that's
+   the local-broker-proxy answer (Layer 3). Do not build another broker inside Prismer; the existing Runtime gateway/proxy owns this flow. Not a Portal-side
+   OAuth roadmap problem.
+4. Mixed setup ("Portal for some things, OpenRouter/Ollama Cloud for the
+   Hermes agent itself") is fully supported. Hermes treats agent
+   provider/model and tool-side LLM calls as independent config; you can
+   point each at a different endpoint.
+
+**Note on the Tool Gateway**: the "no separate accounts, no API key juggling"
+pitch in the Tool Gateway announcement is specifically about Hermes Agent's
+*tools* (web search, browser, image gen, TTS) flowing through the Portal
+subscription when Hermes is configured to use Portal as its provider. It is
+**not** a claim that arbitrary third-party apps inherit Portal auth.

package/built-in-skills/prismer-hermes-agent/references/project-context-files.md

@@ -0,0 +1,55 @@
+# Project Context Files
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Hermes injects project-level instructions into the system prompt by reading context files from the working directory. The discovery order is **first match wins** — only one project context source is loaded per session.
+
+| File (in priority order) | Discovery | Use when |
+|---|---|---|
+| `.hermes.md` / `HERMES.md` | Walks parents up to the git root, stops at git root | You want hierarchical project rules (root + per-package overrides) |
+| `AGENTS.md` / `agents.md` | **Cwd only** — subdirectory and parent copies are ignored | You want portable agent instructions that work the same in Hermes, Claude Code, Codex, etc. |
+| `CLAUDE.md` / `claude.md` | Cwd only | Same as AGENTS.md, Claude-flavored |
+| `.cursorrules` / `.cursor/rules/*.mdc` | Cwd only | Migrating from Cursor |
+
+`SOUL.md` (in `$HERMES_HOME`) is independent and always loaded when present — it sets the agent's identity, not project rules.
+
+### Pick the right one
+
+- **Use `.hermes.md`** when you want Hermes-specific behavior that lives above the cwd (root + subtree), or when you want rules to inherit from a parent directory. The parent walk stops at the git root, so a home-level `.hermes.md` won't leak into every project (a git repo's root is the boundary).
+- **Use `AGENTS.md`** when the same project will also be worked on by other agents (Codex, Claude Code, OpenCode). Those tools all have their own conventions for `AGENTS.md`, and the "cwd only" contract keeps the file portable.
+- **Don't put project rules in `~/.hermes/AGENTS.md`** (or any other home-level location). When Hermes runs with that directory as cwd, the file loads — but only for that one directory. For cross-project context, use `SOUL.md` (in `$HERMES_HOME`, identity-only) or install a skill via `hermes skills install`.
+
+### Size and truncation
+
+Each context file is capped at 20,000 characters. Files longer than that get **head + tail** truncated (the middle is dropped, with a `[...truncated...]` marker). For large project rules, prefer splitting into multiple skills over cramming one file.
+
+### Security
+
+All context files pass through the threat-pattern scanner before reaching the system prompt. Patterns matching prompt injection or promptware are replaced with a `[BLOCKED: ...]` placeholder. This means an `AGENTS.md` containing obvious injection attempts won't reach the model — the scanner blocks the content, not the file, so the rest of the file still loads.
+
+### Disable for one session
+
+`hermes --ignore-rules` skips auto-injection of all project context files (`.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`) **and** `SOUL.md` identity, plus user config, plugins, and MCP servers. Use it to isolate whether a problem is your setup or Hermes itself.
+
+### Example: a small `.hermes.md`
+
+```markdown
+# My Project
+
+Hermes: when working in this repo, follow these rules.
+
+## Build
+- Always run `make test` before declaring a change done.
+- Use `uv run` for Python, not `pip install`.
+
+## Style
+- Prefer `pathlib.Path` over `os.path`.
+- No `print()` in production code — use the `logger`.
+```
+
+That file at `/home/me/projects/myrepo/.hermes.md` is auto-loaded when Hermes runs in any subdirectory of `/home/me/projects/myrepo`, but not when it runs in `/home/me/other-project`.