From 6479465300936ea2a69d7a95b5dad5ca576ae5b6 Mon Sep 17 00:00:00 2001
From: Bezalel <bezalel@noreply.forge.alexanderwhitestone.com>
Date: Tue, 7 Apr 2026 14:10:40 +0000
Subject: [PATCH] docs: add BOOT.md for hermes-agent repository

---
 BOOT.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 BOOT.md

diff --git a/BOOT.md b/BOOT.md
new file mode 100644
index 000000000..b49a70afb
--- /dev/null
+++ b/BOOT.md
@@ -0,0 +1,131 @@
+# BOOT.md — Hermes Agent
+
+Fast path from clone to productive. Target: <10 minutes.
+
+---
+
+## 1. Prerequisites
+
+| Tool | Why |
+|---|---|
+| Git | Clone + submodules |
+| Python 3.11+ | Runtime requirement |
+| uv | Package manager (install: `curl -LsSf https://astral.sh/uv/install.sh \| sh`) |
+| Node.js 18+ | Optional — browser tools, WhatsApp bridge |
+
+---
+
+## 2. First-Time Setup
+
+```bash
+git clone --recurse-submodules https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git
+cd hermes-agent
+
+# Create venv
+uv venv .venv --python 3.11
+source .venv/bin/activate
+
+# Install with all extras + dev tools
+uv pip install -e ".[all,dev]"
+```
+
+> **Common pitfall:** If `uv` is not on PATH, the `setup-hermes.sh` script will attempt to install it, but manual `uv` install is faster.
+
+---
+
+## 3. Smoke Tests (< 30 sec)
+
+```bash
+python scripts/smoke_test.py
+```
+
+Expected output:
+```
+OK: 4 core imports
+OK: 1 CLI entrypoints
+Smoke tests passed.
+```
+
+If imports fail with `ModuleNotFoundError`, re-run: `uv pip install -e ".[all,dev]"`
+
+---
+
+## 4. Full Test Suite (excluding integration)
+
+```bash
+pytest tests/ -x --ignore=tests/integration
+```
+
+> Integration tests require a running gateway + API keys. Skip them unless you are testing platform connectivity.
+
+---
+
+## 5. Run the CLI
+
+```bash
+python cli.py --help
+```
+
+To start the gateway (after configuring `~/.hermes/config.yaml`):
+```bash
+hermes gateway run
+```
+
+---
+
+## 6. Repo Layout for Agents
+
+| Path | What lives here |
+|---|---|
+| `cli.py` | Main entrypoint |
+| `hermes/` | Core agent logic |
+| `toolsets/` | Built-in tool implementations |
+| `skills/` | Bundled skills (loaded automatically) |
+| `optional-skills/` | Official but opt-in skills |
+| `tests/` | pytest suite |
+| `scripts/` | Utility scripts (smoke tests, deploy validation, etc.) |
+| `.gitea/workflows/` | Forge CI (smoke + build) |
+| `.github/workflows/` | GitHub mirror CI |
+
+---
+
+## 7. Gitea Workflow Conventions
+
+- **Push to `main`**: triggers `ci.yml` (smoke + build, < 5 min)
+- **Pull requests**: same CI + notebook CI if notebooks changed
+- **Merge requirement**: green smoke tests
+- Security scans run on schedule via `.github/workflows/`
+
+---
+
+## 8. Common Pitfalls
+
+| Symptom | Fix |
+|---|---|
+| `No module named httpx` | `uv pip install -e ".[all,dev]"` |
+| `prompt_toolkit` missing | Included in `[all]`, but install explicitly if you used minimal deps |
+| CLI hangs on start | Check `~/.hermes/config.yaml` exists and is valid YAML |
+| API key errors | Copy `.env.example` → `.env` and fill required keys |
+| Browser tools fail | Run `npm install` in repo root |
+
+---
+
+## 9. Quick Reference
+
+```bash
+# Reinstall after dependency changes
+uv pip install -e ".[all,dev]"
+
+# Run only smoke tests
+python scripts/smoke_test.py
+
+# Run syntax guard
+python scripts/syntax_guard.py
+
+# Start gateway
+hermes gateway run
+```
+
+---
+
+*Last updated: 2026-04-07 by Bezalel*
-- 
2.43.0