better-dsh 0.2.5 → 0.3.0

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

@@ -1,236 +0,0 @@
----
-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

@@ -1,212 +0,0 @@
----
-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