better-dsh 0.2.5 → 0.3.0

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

@@ -1,196 +0,0 @@
----
-sidebar_position: 3
-sidebar_label: "Git Worktrees"
-title: "Git Worktrees"
-description: "Run multiple Hermes agents safely on the same repository using git worktrees and isolated checkouts"
----
-
-# Git Worktrees
-
-Hermes Agent is often used on large, long‑lived repositories. When you want to:
-
-- Run **multiple agents in parallel** on the same project, or
-- Keep experimental refactors isolated from your main branch,
-
-Git **worktrees** are the safest way to give each agent its own checkout without duplicating the entire repository.
-
-This page shows how to combine worktrees with Hermes so each session has a clean, isolated working directory.
-
-## Why Use Worktrees with Hermes?
-
-Hermes treats the **current working directory** as the project root:
-
-- CLI: the directory where you run `hermes` or `hermes chat`
-- Messaging gateways: the directory set by `terminal.cwd` in `~/.hermes/config.yaml`
-
-If you run multiple agents in the **same checkout**, their changes can interfere with each other:
-
-- One agent may delete or rewrite files the other is using.
-- It becomes harder to understand which changes belong to which experiment.
-
-With worktrees, each agent gets:
-
-- Its **own branch and working directory**
-- Its **own Checkpoint Manager history** for `/rollback`
-
-See also: [Checkpoints and /rollback](./checkpoints-and-rollback.md).
-
-## Quick Start: Creating a Worktree
-
-### From inside a session: `/worktree new`
-
-The fastest path (inspired by Copilot CLI's `/worktree new`): from an
-interactive CLI session, run
-
-```
-/worktree new my-experiment
-```
-
-Hermes creates `.worktrees/my-experiment/` inside the repo (branch
-`hermes/my-experiment`, based on the freshly-fetched remote tip unless
-`worktree_sync: false`), and retargets the session's terminal and file tools
-into it — no restart needed. Omit the name to get a random `hermes-<id>`
-tree. `/worktree` alone shows the active tree; `/worktree list` lists all of
-them. On exit the tree is kept only if it has unpushed commits, exactly like
-`hermes -w`.
-
-### Manually with git
-
-From your main repository (containing `.git/`), create a new worktree for a feature branch:
-
-```bash
-# From the main repo root
-cd /path/to/your/repo
-
-# Create a new branch and worktree in ../repo-feature
-git worktree add ../repo-feature feature/hermes-experiment
-```
-
-This creates:
-
-- A new directory: `../repo-feature`
-- A new branch: `feature/hermes-experiment` checked out in that directory
-
-Now you can `cd` into the new worktree and run Hermes there:
-
-```bash
-cd ../repo-feature
-
-# Start Hermes in the worktree
-hermes
-```
-
-Hermes will:
-
-- See `../repo-feature` as the project root.
-- Use that directory for context files, code edits, and tools.
-- Use a **separate checkpoint history** for `/rollback` scoped to this worktree.
-
-## Running Multiple Agents in Parallel
-
-You can create multiple worktrees, each with its own branch:
-
-```bash
-cd /path/to/your/repo
-
-git worktree add ../repo-experiment-a feature/hermes-a
-git worktree add ../repo-experiment-b feature/hermes-b
-```
-
-In separate terminals:
-
-```bash
-# Terminal 1
-cd ../repo-experiment-a
-hermes
-
-# Terminal 2
-cd ../repo-experiment-b
-hermes
-```
-
-Each Hermes process:
-
-- Works on its own branch (`feature/hermes-a` vs `feature/hermes-b`).
-- Writes checkpoints under a different shadow repo hash (derived from the worktree path).
-- Can use `/rollback` independently without affecting the other.
-
-This is especially useful when:
-
-- Running batch refactors.
-- Trying different approaches to the same task.
-- Pairing CLI + gateway sessions against the same upstream repo.
-
-## Cleaning Up Worktrees Safely
-
-When you are done with an experiment:
-
-1. Decide whether to keep or discard the work.
-2. If you want to keep it:
-   - Merge the branch into your main branch as usual.
-3. Remove the worktree:
-
-```bash
-cd /path/to/your/repo
-
-# Remove the worktree directory and its reference
-git worktree remove ../repo-feature
-```
-
-Notes:
-
-- `git worktree remove` will refuse to remove a worktree with uncommitted changes unless you force it.
-- Removing a worktree does **not** automatically delete the branch; you can delete or keep the branch using normal `git branch` commands.
-- Hermes checkpoint data under `~/.hermes/checkpoints/` is not automatically pruned when you remove a worktree, but it is usually very small.
-
-## Best Practices
-
-- **One worktree per Hermes experiment**
-  - Create a dedicated branch/worktree for each substantial change.
-  - This keeps diffs focused and PRs small and reviewable.
-- **Name branches after the experiment**
-  - e.g. `feature/hermes-checkpoints-docs`, `feature/hermes-refactor-tests`.
-- **Commit frequently**
-  - Use git commits for high‑level milestones.
-  - Use [checkpoints and /rollback](./checkpoints-and-rollback.md) as a safety net for tool‑driven edits in between.
-- **Avoid running Hermes from the bare repo root when using worktrees**
-  - Prefer the worktree directories instead, so each agent has a clear scope.
-
-## Using `hermes -w` (Automatic Worktree Mode)
-
-Hermes has a built‑in `-w` flag that **automatically creates a disposable git worktree** with its own branch. You don't need to set up worktrees manually — just `cd` into your repo and run:
-
-```bash
-cd /path/to/your/repo
-hermes -w
-```
-
-Hermes will:
-
-- Create a temporary worktree under `.worktrees/` inside your repo.
-- Check out an isolated branch (e.g. `hermes/hermes-<hash>`).
-- Run the full CLI session inside that worktree.
-
-This is the easiest way to get worktree isolation. You can also combine it with a single query:
-
-```bash
-hermes -w -z "Fix issue #123"
-```
-
-For parallel agents, open multiple terminals and run `hermes -w` in each — every invocation gets its own worktree and branch automatically.
-
-## Putting It All Together
-
-- Use **git worktrees** to give each Hermes session its own clean checkout.
-- Use **branches** to capture the high‑level history of your experiments.
-- Use **checkpoints + `/rollback`** to recover from mistakes inside each worktree.
-
-This combination gives you:
-
-- Strong guarantees that different agents and experiments do not step on each other.
-- Fast iteration cycles with easy recovery from bad edits.
-- Clean, reviewable pull requests.
-
-## Developing the UI surfaces across worktrees
-
-The TypeScript surfaces (`ui-tui/`, `apps/desktop/`) each need a `node_modules`, which a fresh `npm ci` per worktree duplicates across every branch. If you hack on the TUI or desktop app from multiple worktrees, see [TUI & Desktop from Worktrees](../developer-guide/worktree-ui-dev.md) for the `htui` / `hgui` helpers that share one install by symlink.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/import-from-other-agents.md

@@ -1,74 +0,0 @@
----
-sidebar_position: 9
-title: "Import from Other Agents"
-description: "One-command import of a Claude Code (~/.claude) or OpenAI Codex CLI (~/.codex) setup into Hermes — instructions, allowlists, MCP servers, skills, and memories."
----
-
-# Import from Other Agents
-
-`hermes import-agent` imports your existing **Claude Code** or **OpenAI Codex CLI** setup into Hermes with one command. It follows the same preview-first pattern as [`hermes claw migrate`](../guides/migrate-from-openclaw.md): you always see a per-item plan before anything is written, and `--dry-run` never touches disk.
-
-```bash
-hermes import-agent                    # auto-detect ~/.claude or ~/.codex
-hermes import-agent claude-code        # import from ~/.claude
-hermes import-agent codex              # import from ~/.codex
-hermes import-agent claude-code --dry-run          # preview only
-hermes import-agent codex --source /path/to/.codex # custom location
-hermes import-agent claude-code --overwrite --yes  # replace conflicts, skip prompts
-```
-
-## What gets imported
-
-### Claude Code (`~/.claude`)
-
-| Claude Code | Hermes |
-|---|---|
-| `CLAUDE.md` (global instructions) | Memory entries in `~/.hermes/memories/MEMORY.md` |
-| `settings.json` → `permissions.allow` (`Bash(...)` rules) | `command_allowlist` in `config.yaml` |
-| `settings.json` → `permissions.deny` (`Bash(...)` rules) | `approvals.deny` in `config.yaml` |
-| `mcpServers` (from `~/.claude.json` and `settings.json`) | `mcp_servers` in `config.yaml` |
-| `skills/<name>/` (dirs with `SKILL.md`) | `~/.hermes/skills/claude-code-imports/<name>/` |
-| `commands/*.md` (slash commands) | Skipped with a note — convert them into skills |
-
-Claude's `Bash(npm run test:*)` prefix rules become `npm run test*` globs. Non-`Bash` permission rules (`Read(...)`, `WebFetch`, ...) gate Claude-specific tools and are reported as unmapped rather than imported.
-
-### Codex CLI (`~/.codex`)
-
-| Codex CLI | Hermes |
-|---|---|
-| `AGENTS.md` (global instructions) | Memory entries in `~/.hermes/memories/MEMORY.md` |
-| `config.toml` → `[mcp_servers.*]` | `mcp_servers` in `config.yaml` |
-| `memories/*.md` | Memory entries in `~/.hermes/memories/MEMORY.md` |
-| `skills/<name>/` (dirs with `SKILL.md`) | `~/.hermes/skills/codex-imports/<name>/` |
-
-## What is never imported
-
-**API keys and credentials.** Credential files (`~/.claude/.credentials.json`, `~/.codex/auth.json`) are never read, and MCP server environment variables or headers with secret-looking names (`*_TOKEN`, `*_API_KEY`, `Authorization`, ...) are stripped and listed in the report so you can re-add them deliberately. Run `hermes setup` to configure providers, or add secrets to `~/.hermes/.env`.
-
-## Behavior notes
-
-- **Preview first, always.** The command prints the full plan before applying; in non-interactive sessions it stops at the preview unless you pass `--yes`.
-- **Merges, not replaces.** Memory entries are deduplicated against your existing `MEMORY.md`; allowlist/denylist patterns merge with what's already in `config.yaml`.
-- **Conflicts are skipped by default.** An MCP server or skill that already exists in Hermes is reported as a conflict; pass `--overwrite` to replace it.
-- **Malformed files don't abort the run.** A broken `settings.json` or `config.toml` becomes a per-item error in the report while everything else still imports.
-- Coming from OpenClaw instead? Use [`hermes claw migrate`](../guides/migrate-from-openclaw.md).
-
-## Keeping imports in sync
-
-Every successful import registers its source (and the digest of everything it read) in `~/.hermes/import-sync.json`. When the other agent's setup changes later — new skills, edited `CLAUDE.md`/`AGENTS.md`, added MCP servers — pull the changes in with:
-
-```bash
-hermes import-agent --sync            # re-import every changed source
-hermes import-agent --sync --dry-run  # preview what a sync would do
-```
-
-Sync is prompt-free and cheap: sources whose files are unchanged are skipped by digest comparison, so it is safe to run on a schedule (e.g. a daily [cron job](features/cron.md)). Rules:
-
-- **Memory and config merges stay deduplicating** — a sync never duplicates entries or patterns you already have.
-- **Skills previously imported by `import-agent` are refreshed in place** when the source copy changes.
-- **Skills you created or modified under the import category yourself are never clobbered** — they keep normal conflict semantics (use `--overwrite` on a manual run to force).
-- **Credential files never trigger a sync** — token refreshes in `~/.claude/.credentials.json` or `~/.codex/auth.json` are ignored by the digest, and secrets are still stripped from anything imported.
-
-This mirrors ChatGPT Work's *Settings > Import* automatic updates, adapted to an explicit, inspectable command instead of a background service.
-
-The manifest is per profile. A profile created with `hermes profile create <name> --clone --sync-imports` carries it over, so `hermes -p <name> import-agent --sync` keeps pulling from the same external trees (see [Profiles](./profiles.md#keep-a-clones-imported-agent-setups-synced---sync-imports)).

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

@@ -1,140 +0,0 @@
----
-sidebar_position: 4
-title: Local Models
-description: Run models entirely on your own machine — no account, no API key, nothing leaves your computer.
----
-
-# Local Models
-
-Hermes can run open models entirely on your own machine. It downloads and
-manages the inference engine (llama.cpp), picks the right build of each
-model for your hardware, and handles memory so you never configure context
-sizes, GPU layers, or quantization. You pick a model; Hermes does the rest.
-
-Nothing leaves your computer: no account, no API key, and no network access
-after a model is downloaded.
-
-## Getting started
-
-1. Open **Settings → Providers → Local Models** (or choose **Run models
-   locally** during onboarding).
-2. Click **Install runtime**. Hermes downloads the official llama.cpp
-   build for your hardware (a few hundred MB), verifies it, and keeps it
-   updated.
-3. Pick a model from the catalog and click **Download**.
-4. Click **Use**. New chats now run on the local model.
-
-That's the whole flow. The server starts and stops with Hermes, restarts
-survive app restarts, and switching back to a cloud provider is one click
-in the model picker.
-
-## How Hermes picks what to download
-
-Every model in the catalog is priced against **your machine** before you
-download anything. Each row shows:
-
-- **Memory fit** — green (*Fits your GPU*: runs entirely in GPU memory),
-  amber (*Uses system RAM*: works, but slower), or red (*Too big for this
-  machine*).
-- **Context** — the window the model starts with and the maximum it can
-  grow to.
-- The download size of the build selected for your hardware.
-
-Models ship in several quality grades (quantizations). Hermes picks the
-highest-quality build that runs fully on your GPU; machines with less
-memory get a more compact build of the same model with the same
-guarantees. Below 4-bit the quality loss is too severe, so Hermes never
-offers builds smaller than that — a machine that can't run the 4-bit
-build spilled to system RAM simply can't run that model.
-
-Models that don't fit stay visible with the reason, so you always know
-what a hardware upgrade would unlock.
-
-## How memory management works
-
-Local models live or die by memory placement, so Hermes manages it
-end-to-end and exposes no knobs:
-
-- **Models start at a context window that fully fits your GPU** and grow
-  toward their native maximum as your conversation needs more room. You
-  may see "Context window grown" in the status feed during long sessions
-  — that's the window expanding, not an error.
-- **Every recommended model gets at least a 64K context window.** When a
-  model is larger than your GPU's memory, Hermes deliberately places the
-  overflow in system RAM in the order that hurts least (expert weights
-  first, never the attention cache), trading some speed to protect the
-  context guarantee.
-- **Memory fit includes the launch configuration**, not just the model file:
-  context state, runtime buffers, the vision projector, and MTP buffers all
-  count. For multi-token prediction (MTP), Hermes uses smaller batches when
-  larger batches would spill at the same context window. MTP stays enabled.
-  The same calculation runs when a grown window is restored after restart.
-- **Conversation compression follows a growth check.** If a larger window
-  cannot fit, generation is too slow, or the native maximum is reached,
-  Hermes compresses instead of claiming a window the server did not receive.
-- Idle models are unloaded after 15 minutes to free GPU memory; they
-  reload automatically on the next message.
-
-## The status bar
-
-Right-click the status bar and enable **System resources** to see live GPU
-utilization, GPU memory, and RAM while local models run. The context meter
-always reflects the window the model is actually running with.
-
-## Finding more models
-
-The catalog is a curated starting point, not a boundary. The **Find more
-models** section on the same page searches all of Hugging Face:
-
-- Results show download counts and a per-file fit check sized to your
-  machine, so you know before downloading whether a build runs fully on
-  your GPU.
-- Anything you download behaves exactly like a catalog model — Hermes
-  reads the model file itself to pick its context window and memory
-  placement. The only difference: community models don't carry our
-  "validated" testing badge.
-- Already have a `.gguf` file on disk? **Add model file** links it into
-  your library without copying it (the original stays where it is), and
-  it's usable immediately.
-
-## Using your own llama-server
-
-If a llama-server is already running on your machine, Hermes detects it
-and uses it instead of starting its own. Point a custom endpoint at any
-OpenAI-compatible server for full manual control — the managed runtime is
-a default, not a requirement. For manual setups (Ollama, MLX, custom
-builds, headless CLI machines), see
-[Run Hermes Locally with Ollama](/guides/local-ollama-setup) and
-[Run Local LLMs on Mac](/guides/local-llm-on-mac).
-
-## Configuration
-
-The managed runtime is controlled by the `local_runtime` section of
-`config.yaml`. The desktop UI writes these values for you; they're
-documented for CLI and headless use:
-
-```yaml
-local_runtime:
-  enabled: false     # true = start the managed server with Hermes.
-                     # The desktop "Use" button sets this automatically.
-  backend: auto      # auto | cuda | metal | vulkan | hip | cpu
-  tag: b10362        # pinned llama.cpp release; Hermes updates it with
-                     # each release after re-validation
-```
-
-Models and runtime builds live under the Hermes home directory
-(`models/` and `runtimes/llamacpp/`). Selecting a local model as your
-main model uses the standard `model.provider: llamacpp` +
-`model.default` settings — the same shape as every other provider.
-
-## Requirements and limits
-
-- **Windows and Linux:** NVIDIA GPU (CUDA) or CPU. **macOS:** Apple
-  Silicon (Metal). Vulkan builds serve AMD GPUs.
-- A GPU with 8 GB+ of memory runs the small catalog models comfortably;
-  16 GB+ runs the 27–35B models at high quality.
-- Model downloads are byte-size checked against the catalog during the
-  transfer; an incomplete download is deleted and reported, never
-  half-used. (Only the runtime engine zips are SHA-256 verified.)
-- Deleting a model removes every file it staged, including vision
-  adapters and speculative-decoding companions.

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

@@ -1,157 +0,0 @@
----
-sidebar_position: 3
-title: "Managed Scope"
-description: "Administrator-pinned, user-immutable config and secrets via a system-level managed directory"
----
-
-# Managed Scope
-
-**Managed scope** lets an administrator push a baseline of configuration and
-secrets that a standard (non-root) user **cannot override**. It is intended for
-fleet/org deployments where IT needs to pin, for example, the model provider, a
-shared API base URL, or `security.redact_secrets: true` across every user on a
-machine.
-
-When a managed scope is present, the values it specifies win over the user's
-`~/.hermes/config.yaml`, `~/.hermes/.env`, and even the shell environment — for
-exactly the keys it pins. Everything else stays fully user-controlled.
-
-:::note Different from a package-manager–locked install
-A package-manager–managed install (declarative-distro / formula) blocks *all*
-config mutation and tells you to use your package manager. Managed scope is a
-separate mechanism: it injects *specific immutable values* on a per-key basis
-rather than locking the whole config. The two are independent and can coexist.
-:::
-
-## Where it lives
-
-Managed scope is read from a system-level directory, default `/etc/hermes`:
-
-```text
-/etc/hermes/
-├── config.yaml     # managed config layer (wins over ~/.hermes/config.yaml)
-└── .env            # managed env layer (wins over ~/.hermes/.env + shell)
-```
-
-The directory and files are owned by `root` (directory mode `0755`, files
-`0644`): readable by everyone, writable only by an administrator. **That
-filesystem permission is the enforcement mechanism** — a standard user can read
-the managed files but cannot edit them.
-
-Either file is optional. A missing managed directory or missing file simply
-means "no managed scope," and configuration resolves exactly as it does without
-the feature.
-
-### Relocating the directory
-
-The location can be relocated with the `HERMES_MANAGED_DIR` environment variable
-(for containers or non-`/etc` deployments). This is a deployment/bootstrap path
-knob — like `HERMES_HOME` — set by the same administrator who owns the managed
-files. It is **never persisted** to any `.env` by Hermes.
-
-```bash
-# Point managed scope at a custom directory (set by IT / the deployment, not the user)
-export HERMES_MANAGED_DIR=/opt/org/hermes-policy
-```
-
-:::warning
-A user who can set `HERMES_MANAGED_DIR` can repoint managed scope at a directory
-they control, defeating it. In a real deployment this variable should be fixed
-by the administrator (e.g. baked into the service unit / container image), not
-left user-settable. `hermes doctor` reports the *resolved* managed directory so
-a redirect is visible.
-:::
-
-## Precedence
-
-For the keys a managed layer specifies, the order is (highest wins):
-
-| Tier | config.yaml | .env |
-|---|---|---|
-| 1 | `/etc/hermes/config.yaml` (managed) | `/etc/hermes/.env` (managed) |
-| 2 | `~/.hermes/config.yaml` (user) | `~/.hermes/.env` (user) |
-| 3 | built-in defaults | pre-existing shell environment |
-
-Merging is **leaf-level**: pinning `model.default` does not freeze the rest of
-`model.*`. A managed `config.yaml` of:
-
-```yaml
-model:
-  default: org/standard-model
-```
-
-forces `model.default` for every user while leaving `model.fallback` (and every
-other key) under user control.
-
-:::note Precedence note
-For the keys it pins, managed scope deliberately wins over the shell environment
-too — otherwise it would not be "managed." This is the one place that inverts the
-usual "an environment variable overrides config.yaml" rule, and it applies only
-to the specific keys the managed layer specifies.
-:::
-
-## Seeing what's managed
-
-```bash
-hermes config        # shows a header naming the managed source + the pinned keys
-hermes doctor        # reports the resolved managed dir + pinned key counts
-```
-
-If you try to change a managed value, Hermes refuses and names the source:
-
-```bash
-$ hermes config set model.default my/model
-Cannot set 'model.default': it is managed by your administrator
-(/etc/hermes/config.yaml) and cannot be changed.
-```
-
-The same applies to managed secrets — `hermes config set` / setup will not write
-a user value for an env key pinned by the managed `.env`.
-
-## Setting up a managed scope (administrators)
-
-```bash
-sudo mkdir -p /etc/hermes
-
-# Pin some config values for every user on this machine
-sudo tee /etc/hermes/config.yaml >/dev/null <<'YAML'
-model:
-  provider: nous
-security:
-  redact_secrets: true
-YAML
-
-# Optionally pin a shared, non-sensitive env value
-sudo tee /etc/hermes/.env >/dev/null <<'ENV'
-OPENAI_API_BASE=https://inference.example.com/v1
-ENV
-
-sudo chmod 0755 /etc/hermes
-sudo chmod 0644 /etc/hermes/config.yaml /etc/hermes/.env
-```
-
-Changes take effect on the next Hermes start (a malformed managed file is logged
-loudly and ignored — it never blocks startup, but the admin should check
-`hermes doctor` to confirm the policy is being applied).
-
-## Security model and limitations (v1)
-
-- **Enforcement is filesystem permissions only.** If a user has write access to
-  the managed directory (or runs Hermes as `root`), managed scope is advisory.
-- **The managed `.env` is world-readable** (`0644`), so any local user can read
-  secrets pushed through it. Use it for shared, non-sensitive values (an org API
-  base URL, feature defaults) rather than high-sensitivity secrets.
-- **The agent's own tools are not hard-blocked from a managed *env* value.** A
-  managed environment variable is applied at startup, but nothing stops the
-  agent from setting a different value inside its own subprocess shell. v1 is a
-  management-convenience boundary against a normal user, not an un-escapable
-  sandbox.
-
-The following are intentionally **out of scope for v1** and may come later:
-
-- A hard boundary that the agent itself cannot escape.
-- Native managed locations on macOS and Windows (v1 is Linux/POSIX-first).
-- Drop-in fragment directories (`managed.d/`) for layered policy.
-- Signed / integrity-checked managed files.
-- Remote / device-management (MDM) delivery.
-- Tighter (group-scoped) permissions for managed secrets.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Messaging Gateway",
-  "position": 3,
-  "link": {
-    "type": "doc",
-    "id": "user-guide/messaging/index"
-  }
-}