# Wizard Environment Contract

> **Version:** 1.0.0
> **Owner:** Wizard Council (Bezalel Epic-004)
> **Last updated:** 2026-04-06

This document defines the minimum viable state every forge wizard must maintain.
A wizard that satisfies all requirements is considered **forge-ready**.

---

## 1. Python Runtime

| Requirement | Minimum | Notes |
|-------------|---------|-------|
| Python version | 3.11 | 3.12+ recommended |
| Virtual environment | Activated | `source venv/bin/activate` before running |

Run `python --version` to verify.

---

## 2. Core Package Dependencies

All packages in `requirements.txt` must be installed and importable.
Critical packages: `openai`, `anthropic`, `pyyaml`, `rich`, `requests`, `pydantic`, `prompt_toolkit`.

**Verify:**
```bash
python wizard-bootstrap/wizard_bootstrap.py
```

---

## 3. LLM Provider Key

At least one LLM provider API key must be set in `~/.hermes/.env`:

| Variable | Provider |
|----------|----------|
| `OPENROUTER_API_KEY` | OpenRouter (200+ models) |
| `ANTHROPIC_API_KEY` | Anthropic Claude |
| `ANTHROPIC_TOKEN` | Anthropic Claude (alt) |
| `OPENAI_API_KEY` | OpenAI |
| `GLM_API_KEY` | z.ai/GLM |
| `KIMI_API_KEY` | Moonshot/Kimi |
| `MINIMAX_API_KEY` | MiniMax |

---

## 4. Gitea Authentication

| Requirement | Details |
|-------------|---------|
| Variable | `GITEA_TOKEN` or `FORGE_TOKEN` |
| Scope | Must have repo read/write access |
| Forge URL | `https://forge.alexanderwhitestone.com` (or `FORGE_URL` env var) |

The wizard must be able to create and merge PRs on the forge.

---

## 5. Telegram Connectivity (Gateway Wizards)

Wizards that operate via the messaging gateway must also satisfy:

| Requirement | Details |
|-------------|---------|
| Variable | `TELEGRAM_BOT_TOKEN` |
| Home channel | `TELEGRAM_HOME_CHANNEL` |
| API reachability | `api.telegram.org` must be reachable |

CLI-only wizards may skip Telegram checks.

---

## 6. HERMES_HOME

| Requirement | Details |
|-------------|---------|
| Default | `~/.hermes` |
| Override | `HERMES_HOME` env var |
| Permissions | Owner-writable (700 recommended) |

The directory must exist and be writable before any hermes command runs.

---

## 7. Skill Dependencies (Per-Skill)

Each skill may declare binary and environment-variable dependencies in its
`SKILL.md` frontmatter:

```yaml
---
name: my-skill
dependencies:
  binaries: [ffmpeg, imagemagick]
  env_vars: [MY_API_KEY]
---
```

A wizard must satisfy all dependencies for any skill it intends to run.

**Check all skill deps:**
```bash
python wizard-bootstrap/dependency_checker.py
```

---

## 8. Enforcement

### New Wizard Onboarding

Run the bootstrap script before going online:

```bash
python wizard-bootstrap/wizard_bootstrap.py
```

Resolve all failures before beginning work.

### Ongoing Compliance

A monthly audit runs automatically (see `wizard-bootstrap/monthly_audit.py`).
The report is saved to `~/.hermes/wizard-council/audit-YYYY-MM.md` and posted
to the `wizard-council-automation` Telegram channel.

### Skill Drift

Run the skills audit to detect and fix drift:

```bash
python wizard-bootstrap/skills_audit.py          # detect
python wizard-bootstrap/skills_audit.py --fix    # sync
```

---

## 9. Contract Versioning

Changes to this contract require a PR reviewed by at least one wizard council
member. Bump the version number and update the date above with each change.

---

## Quick Reference

```bash
# Full environment validation
python wizard-bootstrap/wizard_bootstrap.py

# Skills drift check
python wizard-bootstrap/skills_audit.py

# Dependency check
python wizard-bootstrap/dependency_checker.py

# Full monthly audit (all three checks, saves report)
python wizard-bootstrap/monthly_audit.py
```