better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/pets.md

@@ -0,0 +1,236 @@
+---
+sidebar_position: 11
+title: "Pets (Petdex Mascots)"
+description: "Adopt an animated mascot that reacts to agent activity across the CLI, TUI, and desktop app"
+---
+
+# Pets
+
+Hermes can show an animated **pet** — a small mascot sprite that reacts to what
+the agent is doing (idle, running a tool, thinking, finishing, failing) across
+the **CLI**, **TUI**, and **desktop app**. Pets come from the public
+[petdex](https://github.com/crafter-station/petdex) gallery.
+
+Pets are purely cosmetic. They have **no effect on prompt caching, tokens, or
+the agent's behavior** — the sprite is a display concern only. The feature is
+**off by default** and stays dormant until you install and select a pet.
+
+## How it works
+
+- Pets are installed into your profile's `pets/` directory
+  (`<HERMES_HOME>/pets/<slug>/`), so each [profile](../profiles.md) keeps its
+  own set.
+- Selecting a pet writes `display.pet.slug` and `display.pet.enabled` to
+  `config.yaml` — nothing is stored as a secret or env var.
+- Each surface watches the activity it already tracks and maps it to one of six
+  animation states. The mapping lives in one place so every surface behaves the
+  same:
+
+  | Agent activity | Pet state |
+  | --- | --- |
+  | A tool/turn just failed | `failed` |
+  | A plan finished (all todos done) | `jump` (celebrate) |
+  | A turn finished cleanly | `wave` |
+  | A tool is executing | `run` |
+  | The model is thinking/reading | `review` |
+  | Turn in flight (unspecified) | `run` |
+  | Blocked on you (a clarify/approval prompt is open) | `waiting` (falls back to `idle` on legacy 8-row sheets) |
+  | Nothing happening | `idle` |
+
+## Rendering
+
+In the terminal (CLI/TUI), Hermes renders the sprite at full fidelity when your
+terminal supports a graphics protocol (**kitty**, **Ghostty**, **WezTerm**,
+**iTerm2**, or **sixel**). Otherwise it falls back automatically to a truecolor
+Unicode **half-block** rendering. Inside a pipe or redirect (no TTY), terminal
+rendering is disabled by design.
+
+The desktop app draws the pet as a floating sprite on a canvas and toggles it
+from **Settings → Appearance**.
+
+## Quick start (CLI)
+
+```bash
+# Browse the gallery (filter by substring)
+hermes pets list
+hermes pets list cat
+
+# Install a pet and make it active in one step
+hermes pets install boba --select
+
+# Preview / animate it in your terminal (Ctrl+C to stop)
+hermes pets show
+
+# Check your setup
+hermes pets doctor
+```
+
+## `hermes pets` commands
+
+| Goal | Command |
+| --- | --- |
+| Browse the gallery | `hermes pets list [query] [--limit N]` |
+| List installed pets | `hermes pets list --installed` |
+| Install a pet | `hermes pets install <slug> [--select] [--force]` |
+| 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 | `hermes pets show [slug] [--state <s>] [--cycle] [--once] [--mode <m>] [--scale <f>]` |
+| Disable the pet | `hermes pets off` |
+| Remove an installed pet | `hermes pets remove <slug>` |
+| Diagnose setup | `hermes pets doctor` |
+
+`hermes pets show` flags:
+
+- `--state` — play a single state (`idle`, `wave`, `run`, `failed`, `review`,
+  `jump`).
+- `--cycle` — cycle through every state.
+- `--once` — play once instead of looping.
+- `--mode` — override the render protocol (`kitty`, `iterm`, `sixel`,
+  `unicode`, `auto`).
+- `--scale` — override the on-screen scale (`0` = use config).
+
+## `/pet` slash command
+
+Inside the CLI and TUI you can manage the pet without leaving the session:
+
+- `/pet` — toggle the pet on/off (adopts the first installed pet if none is
+  active).
+- `/pet list` — browse the gallery.
+- `/pet scale <factor>` — resize the pet everywhere (e.g. `/pet scale 0.5`).
+- `/pet <slug>` — adopt a specific pet.
+- `/pet off` — disable the pet.
+
+In the TUI, `/pet list` opens an interactive picker overlay; in the desktop app
+it opens the Cmd+K pet palette.
+
+## Generating a pet (`/hatch`)
+
+Beyond installing pre-made pets from the gallery, Hermes can **generate a brand-new pet** from a text description — its own AI sprite-generation pipeline.
+
+- CLI/TUI: `/hatch <description>` (alias `/generate-pet`), or `hermes pets` → the generate flow.
+- Desktop app: the Pokédex-style **generate** UI — an animated egg, hatch FX, and a draft picker.
+
+How generation works (a two-step, cost-bounded flow):
+
+1. **Base drafts** — a handful of cheap, prompt-only "what should this pet look like" variants are generated. You pick one, or remix/retry for a fresh round.
+2. **Hatch** — the chosen base is used as a reference image to generate one grounded animation row per Hermes state (idle, thinking, tool use, etc.), which are deterministically sliced into frames and packed into a standard petdex/Codex atlas (8×9 grid of 192×208 cells). The result is a valid spritesheet you keep — and could `petdex submit`.
+
+### Image backend
+
+Generation uses the active [image-generation provider](/user-guide/features/image-generation), but it requires **reference-image grounding** so each animation row stays the same character as the base. Reference-capable backends: **Nous Portal**, **OpenRouter**, **OpenAI** (`gpt-image-2`), and **Krea**. OpenRouter/Nous run a quality-first model chain by default.
+
+- Resolution order prefers Nous Portal → OpenAI → OpenRouter.
+- If no reference-capable backend is configured, generation surfaces an actionable error pointing you to `hermes tools` → Image Generation. (Installing/adopting existing gallery pets needs no image backend.)
+- Override the backend with the `HERMES_PET_IMAGE_PROVIDER` env var (e.g. `HERMES_PET_IMAGE_PROVIDER=openrouter`).
+
+## Desktop app
+
+In the desktop app you can manage the pet two ways:
+
+- **Cmd+K → "Pets…"** — browse, search, adopt, and toggle pets without leaving
+  the keyboard (mirrors the theme picker).
+- **Settings → Appearance** — the same gallery plus a **size slider** that
+  resizes the floating mascot live as you drag.
+
+Both adopt/toggle/resize the floating mascot in place — size changes apply
+instantly; adopting a new pet lights it up within a moment.
+
+### Roaming
+
+Settings → Appearance has a **Roam** toggle: when enabled, the pet wanders the
+window on its own while the agent is idle — walking surfaces, pausing, and
+hopping between spots. Roaming only runs while the pet is in-window, active,
+and the agent is at rest; any agent-driven state (working, celebrating)
+immediately takes over. The toggle is off by default and persists across
+restarts.
+
+### Alt+wheel resizing
+
+Hold **Alt** and scroll the mouse wheel over the pet to resize it in place —
+in the app window and on the popped-out overlay alike. The overlay zooms
+toward the cursor position and the resulting scale is persisted, so it
+survives restarts and stays in sync with the in-app pet.
+
+### Vibe reactions
+
+Say something nice to the agent — "good bot", "thank you", "ily", `<3`, or a
+heart emoji — and the pet reacts with floating hearts (desktop) or a heart
+flash (CLI/TUI). Detection is a curated, token-free lexicon matched locally on
+each user message (no model call); it fires on affection and gratitude aimed at
+the agent, not general positive sentiment. All surfaces — CLI pet, TUI, desktop
+floating pet, and the pop-out overlay — react off the same signal.
+
+### Pop-out overlay
+
+**Shift-click** the floating pet to pop it out into its own transparent,
+always-on-top desktop window. Out there it stays visible while Hermes is
+minimized (Codex-style), so a glance tells you what the agent is doing.
+
+Gestures once it's popped out:
+
+| Gesture | Action |
+| --- | --- |
+| **Drag** | Move the pet anywhere on screen, even outside the app. Its spot and in/out state persist across restarts. |
+| **Single-click** | Open a mini composer to send a prompt to the most recent session — without surfacing the app. |
+| **Double-click** | Toggle the app window: minimize it if it's up front, restore it if it's hidden. |
+| **Shift-click** | Pop the pet back into the window. |
+| **Mail icon** | Appears only when a turn finished while you were away; click to raise the app on the most recent thread (and mark it read). |
+
+Only the popped-out pet shows a **speech bubble** (`working…`, `thinking…`,
+`your turn`, …) — in-window the app itself is the surface, so the pet stays
+quiet there.
+
+The overlay is a pure puppet of the in-app pet — it carries no separate gateway
+connection and never appears in the dock or app switcher.
+
+## Configuration
+
+All settings live under `display.pet` in `config.yaml`:
+
+```yaml
+display:
+  pet:
+    enabled: false        # master on/off (true once you select a pet)
+    slug: ""              # active pet; empty = first installed
+    render_mode: auto      # auto | kitty | iterm | sixel | unicode | off
+    scale: 0.33           # master size knob (relative to native 192x208 frames)
+    unicode_cols: 0       # hard override for terminal width (0 = derive from scale)
+```
+
+- **`scale`** is the single master size knob. One number shrinks every surface:
+  the desktop canvas scales its pixels by it, and the CLI/TUI derive their
+  terminal column width from it. The half-block fallback clamps to a legibility
+  floor — it can't shrink as far as true-pixel kitty/GUI rendering without
+  turning to mush, so the same `scale` looks crisp under kitty but is floored in
+  half-blocks.
+- **`render_mode: auto`** detects kitty/iTerm2/sixel and falls back to unicode
+  half-blocks. Set it explicitly to force a protocol or `off` to disable
+  terminal rendering while keeping the pet on the desktop.
+- **`unicode_cols`** pins the terminal column width independently of `scale`;
+  leave it at `0` to derive width from `scale`.
+
+## Troubleshooting
+
+Run `hermes pets doctor` — it reports:
+
+- the pets directory and which pets are installed,
+- `display.pet.enabled`, `display.pet.slug`, and the resolved active pet,
+- the configured `render_mode`, the detected terminal graphics protocol, and the
+  effective mode for a TTY,
+- whether Pillow (used for sprite decoding) is importable.
+
+It prints `✓ ready` once a pet is installed, selected, enabled, and Pillow is
+available.
+
+Common gotchas:
+
+- 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`.
+
+## See also
+
+- The [`hermes-agent` skill](../skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md)
+  lets the agent install and switch pets for you on request (see its
+  `references/petdex.md`).

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/plugin-catalog.md

@@ -0,0 +1,212 @@
+---
+sidebar_position: 13
+sidebar_label: "Plugin Catalog"
+title: "Plugin Catalog"
+description: "Browse and install reviewed, SHA-pinned Hermes plugins from the curated catalog"
+---
+
+# Plugin Catalog
+
+The plugin catalog is a curated, human-reviewed directory of Hermes plugins you
+can install by name with a single command:
+
+```bash
+hermes plugins install <name>
+```
+
+Browse it visually at **[/docs/plugins](/plugins)** — entries are shelved by
+category (Memory, Desktop, Platforms, Web & Browser, Tools, Voice, Automation,
+Models), with search, tier filters (Official / Community), capability chips, and
+**Install in Hermes** buttons and copyable CLI commands for every entry.
+
+In Desktop, open **Capabilities → Plugins → Browse** for the native catalog
+view. It is not an embedded website. **Installed** is a separate tab backed
+by the app's desktop-plugin registry and the selected profile's agent-plugin
+state, rather than catalog metadata. Skills uses the same **Installed / Browse**
+layout; search stays at the top and the tab switch and actions share one row.
+Browse defaults to cards. The list and card icons beside the filters switch
+layouts, preserving search and filters and remembering the choice across both
+catalogs.
+
+The catalog complements — it does not replace — the existing
+[plugin system](plugins.md). Anything you can install from the catalog is a
+normal plugin under the hood; the catalog just adds discovery and a review
+layer on top.
+
+### Published browse data
+
+The website and Desktop read the same generated CDN snapshot:
+[`https://hermes-agent.nousresearch.com/docs/api/plugins.json`](https://hermes-agent.nousresearch.com/docs/api/plugins.json).
+Desktop fetches it through
+`https://nousresearch.github.io/hermes-agent/docs/api/plugins.json`; the public
+docs alias serves the same data. The docs build reads `plugin-catalog/*.yaml`
+and adds cached repository star counts. It also publishes the installer's
+removed-entry list. Neither
+Browse view crawls source repositories or queries the GitHub API live.
+
+This browse snapshot is distinct from the installer's
+[`plugin-catalog.json`](#live-refresh), which resolves catalog names and pins.
+
+## What's in an entry
+
+Each catalog entry is a small YAML file in the
+[`plugin-catalog/`](https://github.com/NousResearch/hermes-agent/tree/main/plugin-catalog)
+directory of the hermes-agent repository, declaring:
+
+| Field | Meaning |
+|---|---|
+| `name` | The catalog key you pass to `hermes plugins install` |
+| `repo` | The plugin's public git repository |
+| `sha` | The **exact 40-hex commit** that was reviewed — installs check out this pin, not a branch tip |
+| `tier` | `official` (maintained by NousResearch) or `community` |
+| `category` | Browse shelf: `desktop` (default), `memory`, `platform`, `web`, `tools`, `voice`, `automation`, `models` or `general` |
+| `maintainer` | Who owns the plugin |
+| `capabilities` | Declared tools, hooks, middleware, and required env vars |
+| `requires_hermes` | Minimum Hermes version, e.g. `>=0.19` (optional) |
+| `platforms` | OS restrictions, empty = all (optional) |
+| `docs_url` | External documentation link (optional) |
+
+## Trust model
+
+The catalog is designed so you know exactly what you're installing:
+
+- **Human-merged admission.** Every entry (and every pin update) lands via a
+  pull request reviewed by a maintainer. Nothing enters the catalog
+  automatically.
+- **Exact SHA pins.** Entries pin a specific commit, not a branch. A plugin
+  author pushing new code to their repo does **not** change what the catalog
+  installs — updating the pin requires another reviewed PR.
+- **Capability declarations.** Entries state up front which tools, hooks, and
+  middleware the plugin provides and which environment variables (API keys
+  etc.) it needs, so you can judge its blast radius before installing.
+- **Removed list.** Plugins pulled from the catalog (for example after a
+  security incident) go on `plugin-catalog/removed.yaml` with a reason and
+  date. The installer refuses to install anything on the removed list.
+- **Installed ≠ enabled.** Installing a catalog plugin puts it on disk; like
+  any plugin it must still be enabled before it loads. See
+  [Plugins → Enabling and disabling](plugins.md).
+
+:::warning Catalog review is a point-in-time review
+A catalog entry means the pinned commit was looked at by a human, capability
+declarations were checked, and the repo met the submission bar. It is not a
+security audit, and it says nothing about other commits in the same
+repository. Review the code of anything you give credentials to.
+:::
+
+## Installing from the catalog
+
+On the website, **Install in Hermes** opens a protocol link of this form:
+
+```text
+hermes://plugin/install?repo=owner%2Frepo&catalog_name=example-plugin&sha=0123456789abcdef0123456789abcdef01234567
+```
+
+`repo` is URL-encoded, including any `#subdir`. Desktop asks you to review the
+source, destination and components before confirming; the link does not
+auto-install. For the agent-plugin component, the backend resolves
+`catalog_name` to its reviewed pin. The link's `sha` is **display metadata
+only**, not authority to choose or override a commit, and it is not a pin
+guarantee for a standalone desktop plugin.
+
+Use an updated Desktop build for the catalog parameters (and for the public
+Skills Hub's new `hermes://skill/install?identifier=...` route). Older builds
+may only understand repository-only plugin links. The expanded cards retain
+CLI commands, so you can install by catalog name without Desktop:
+
+```bash
+# Install a reviewed catalog entry by name (checks out the pinned SHA)
+hermes plugins install <name>
+
+# Then enable it, as with any plugin
+hermes plugins enable <name>
+```
+
+The install prompt shows the entry's capability summary — declared tools,
+hooks, and required env vars — before anything is cloned.
+
+The catalog name and the plugin's own manifest name can differ; `hermes
+plugins install` prints the installed name, and `enable` takes that one. For
+example the `touchdesigner` entry (a portable Agent Plugins v1 package that
+bundles the twozero MCP server with the `touchdesigner-mcp` skill) installs as
+`td`, kept short so its generated MCP tool names stay under provider
+function-name limits:
+
+```bash
+hermes plugins install touchdesigner
+hermes plugins enable td
+```
+
+Portable packages can also carry a stdio MCP server. The `snyk` entry pins the
+Snyk CLI (`npx -y snyk@<version> mcp`) and bundles the `snyk-security-scan`
+skill, so one install gives Hermes code, dependency, container and IaC scanning
+plus the workflow for using it; the catalog name and manifest name match:
+
+```bash
+hermes plugins install snyk
+hermes plugins enable snyk
+```
+
+### Updating a catalog install
+
+`hermes plugins update <name>` never runs `git pull` for catalog installs —
+it compares your installed pin against the current catalog pin and, when the
+catalog moved (via a reviewed PR), force-reinstalls at the new SHA. Your
+enabled/disabled state is preserved. `hermes plugins list` shows catalog
+installs as `catalog:<tier>@<sha>` so you can see provenance at a glance.
+
+### Names not in the catalog
+
+A bare name that isn't a catalog entry is an error: there is no second,
+unreviewed name index. Install such plugins by `owner/repo` or Git URL instead
+(custom source, see below), or submit them to the catalog.
+
+### Live refresh
+
+The docs build publishes the catalog as one JSON document
+(`https://hermes-agent.nousresearch.com/docs/api/plugin-catalog.json`).
+`search`/`install`/`update` fetch it at most every six hours and cache it under
+`~/.hermes/cache/`, so new entries and removals reach installed clients without
+updating Hermes. Offline, the copy shipped with your checkout is used. Removals
+from the in-tree list and the live list are always both enforced.
+
+### Custom git URLs are different
+
+`hermes plugins install <git-url>` still works for any repository, but it
+bypasses the catalog entirely:
+
+- **No review** — you get whatever is at the branch tip, not a reviewed pin.
+- **A warning banner** is shown to make clear the code is unvetted.
+- The removed list is still consulted (a known-bad repo is refused by URL).
+
+Use the git-URL path for your own plugins and repos you already trust; use the
+catalog for discovery.
+
+## Submitting a plugin to the catalog
+
+Submissions are pull requests that add one `plugin-catalog/<name>.yaml` file.
+The full checklist lives in the
+[plugin-catalog README](https://github.com/NousResearch/hermes-agent/tree/main/plugin-catalog);
+in short, an entry must be:
+
+1. **Owner-submitted** — the PR author owns or maintains the plugin repo.
+   Maintainers also add batches of community plugins from a reviewed sweep
+   (each pin validated and scanned at the pinned commit); if yours was swept
+   in and you want it changed or removed, open a PR on your entry.
+2. **A public repository** — the `repo` URL is publicly cloneable.
+3. **Released** — the repo has real releases/tags, not just a default branch.
+4. **Passing validation** — the catalog validation GitHub Action is green on
+   the PR (schema, SHA format, reachability).
+5. **Not self-updating** — the catalog build must not download and replace
+   its own files; the pinned SHA is the only update path (a SHA-bump PR plus
+   `hermes plugins update <name>`).
+
+Pin updates (bumping `sha` to a newer commit) follow the same PR + review
+process.
+
+## See also
+
+- [Plugins](plugins.md) — the plugin system itself: manifest format, enabling,
+  configuration
+- [Built-in Plugins](built-in-plugins.md) — plugins that ship with Hermes
+- [Build a Hermes Plugin](/developer-guide/plugins) — write your own
+- [Plugin Catalog page](/plugins) — the browsable catalog