# Jovaltus Setup

> Guides the agent through setting up the Jovaltus Hermes plugin from scratch. Use when the user wants to install, set up, enable, or configure Jovaltus; when they ask '幫我裝 jovaltus', 'setup jovaltus', 'install jovaltus plugin', or 'configure jovaltus agent profile'. Do NOT use for using Jovaltus pipeline skills (discuss, design, execute, etc.) or for editing Jovaltus source code.

- Skill: `uniterra-solutions/jovaltus-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uniterra-solutions/jovaltus-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uniterra-solutions/jovaltus-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Uniterra-Solutions (https://skillmd.com/u/uniterra-solutions)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/uniterra-solutions/jovaltus-setup

---


# Jovaltus Setup

Guide the agent through installing and configuring the Jovaltus Hermes plugin
by reading the official documentation. Never hardcode setup steps — always
fetch the latest docs from the Jovaltus repository to avoid staleness.

## Goal

A working Jovaltus installation: plugin enabled, profile created, skills
available, and installation verified.

## Core Principle: Docs Are the Source of Truth

This skill does not contain setup instructions. It tells the agent **where**
to find them. The Jovaltus docs live in the canonical GitHub repository and
are the authoritative reference for every step.

If a step in the docs fails, do not guess a fix — check the troubleshooting
section in the same document first, then consult the repo's README.

## Workflow

### Phase 1: Fetch the Setup Documentation

Read the canonical setup guide from the Jovaltus repository:

```
https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/setup.md
```

This document covers prerequisites, installation, plugin enabling, profile
creation, and verification. It is the single source of truth.

### Phase 2: Execute Setup Steps in Order

Follow every step from `setup.md` exactly as written, in the order they
appear. Do not skip or reorder steps.

After each step, verify success before moving to the next one:

- **Prerequisites check**: Confirm every required tool is installed at the
  minimum version before proceeding.
- **Install**: Run the install command and confirm no errors.
- **Enable**: Run `hermes plugins enable jovaltus` and verify with
  `hermes plugins list`.
- **Setup**: Run `hermes jovaltus setup`. In non-TTY environments the
  defaults are safe — the plugin handles this automatically.
- **Verify**: Run `hermes jovaltus status` and check the output matches the
  expected shape from the docs.

### Phase 3: Verify Skills Are Available

After setup completes, confirm the bundled skills are discoverable:

```bash
hermes -p jovaltus-agent
```

In the session, ask the agent to list skills matching "jovaltus". Expect
to see all 11 bundled skills (8 pipeline + 3 utility).

### Phase 4: Troubleshoot If Needed

If any step fails, consult these resources in order:

1. The troubleshooting table in the [Jovaltus README](https://github.com/Uniterra-Solutions/jovaltus#疑難排解)
2. The [Jovaltus architecture doc](https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/architecture.md) for understanding how the plugin works
3. The [Jovaltus workflows doc](https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/workflows.md) for common recipes

Common issues and their first checks:

| Symptom | First check |
|---------|-------------|
| Skills not appearing | Plugin symlink in profile's `plugins/` directory |
| "No inference provider configured" | Profile `config.yaml` has model + provider |
| "Unknown command: jovaltus" | `hermes plugins enable jovaltus` was run |
| 401 Authentication Error | Profile `.env` has API key |

## Gotchas

- **The setup doc is the authority.** If this skill's workflow contradicts
  `setup.md`, the doc wins. The doc is updated with the plugin; this skill
  may lag.
- **Non-TTY environments are supported.** `hermes jovaltus setup` detects
  when no terminal is available and uses safe defaults — no SOUL.md
  overwrite, no interactive prompts. Do not try to work around this.
- **Profile binding uses symlinks, not directory installs.** The old
  `hermes plugins install <directory>` approach is deprecated for Jovaltus.
  Always use `pip install jovaltus` + `hermes plugins enable jovaltus`.
- **fabricium is auto-installed.** Jovaltus self-bootstraps its dependency
  on import — no need to install it separately.
- **The `jovaltus-agent` profile is separate from other profiles.** It is
  not directory-bound; the same profile works across all projects.

## References

- [Jovaltus Setup Guide](https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/setup.md) — Prerequisites, install, enable, verify
- [Jovaltus README](https://github.com/Uniterra-Solutions/jovaltus#installation-and-usage) — Installation overview + troubleshooting table
- [Jovaltus Architecture](https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/architecture.md) — System design, skill-driven pipeline
- [Jovaltus Workflows](https://raw.githubusercontent.com/Uniterra-Solutions/jovaltus/main/docs/workflows.md) — Common recipes and debugging