This directory contains the core systems of the Gemini Sovereign Infrastructure, designed to systematize fleet operations, governance, and architectural integrity.
## Principles
1.**Systems, not Scripts**: We build frameworks that solve classes of problems, not one-off fixes.
2.**Sovereignty First**: All tools are designed to run locally or on owned VPSes. No cloud dependencies.
3.**Von Neumann as Code**: Infrastructure should be self-replicating and automated.
4.**Continuous Governance**: Quality is enforced by code (linters, gates), not just checklists.
## Tools
### [OPS] Provisioning & Fleet Management
- **`provision_wizard.py`**: Automates the creation of a new Wizard node from zero.
- Creates DigitalOcean droplet.
- Installs and builds `llama.cpp`.
- Downloads GGUF models.
- Sets up `systemd` services and health checks.
- **`fleet_llama.py`**: Unified management of `llama-server` instances across the fleet.
-`status`: Real-time health and model monitoring.
-`restart`: Remote service restart via SSH.
-`swap`: Hot-swapping GGUF models on remote nodes.
- **`skill_installer.py`**: Packages and deploys Hermes skills to remote wizards.
- **`model_eval.py`**: Benchmarks GGUF models for speed and quality before deployment.
- **`phase_tracker.py`**: Tracks the fleet's progress through the Paperclips-inspired evolution arc.
- **`cross_repo_test.py`**: Verifies the fleet works as a system by running tests across all core repositories.
- **`self_healing.py`**: Auto-detects and fixes common failures across the fleet.
- **`agent_dispatch.py`**: Unified framework for tasking agents across the fleet.
- **`telemetry.py`**: Operational visibility without cloud dependencies.
- **`gitea_webhook_handler.py`**: Handles real-time events from Gitea to coordinate fleet actions.
### [ARCH] Governance & Architecture
- **`architecture_linter_v2.py`**: Automated enforcement of architectural boundaries.
- Enforces sidecar boundaries (no sovereign code in `hermes-agent`).
- Prevents hardcoded IPs and committed secrets.
- Ensures `SOUL.md` and `README.md` standards.
- **`adr_manager.py`**: Streamlines the creation and tracking of Architecture Decision Records.
-`new`: Scaffolds a new ADR from a template.
-`list`: Provides a chronological view of architectural evolution.
## Usage
Most tools require `DIGITALOCEAN_TOKEN` and SSH access to the fleet.
The fleet inventory is defined in `timmy-config/config.yaml` under the `fleet:` key. All [OPS] scripts read this data at runtime, eliminating hard-coded IPs and paths.
### `fleet.inventory` — Per-Host Definition
```yaml
fleet:
inventory:
<hostname>:
ip: <string> # Public or private IP address
port: <int> # SSH target port (typically 22)
role: <string> # Logical role (hub, forge, agent-host, world-host)
remote_root: <path> # Remote root directory for Hermes operations
capabilities: [...] # Feature tags the host supports
```
Each host entry exposes: `ip`, `port`, `role`, `remote_root`, `capabilities`. The `capabilities` tag is freeform but standardized across the fleet (e.g., `gateway`, `orchestrator`, `forge`, `agent-host`, `llm-host`, `world-host`).
### `fleet.path_contracts` — Path Abstractions
```yaml
fleet:
path_contracts:
hermes_agent_local: ../hermes-agent # Path to local hermes-agent repo (relative to timmy-config)
hermes_remote: /opt/hermes # Remote Hermes root on fleet nodes
All scripts reference paths via `get_path_contract(key, default)` or `get_remote_root()` helpers. This centralizes path management across local (mac) and remote wizards.
### Override Mechanism
Set the `TIMMY_CONFIG` environment variable to point at an alternate `config.yaml`:
