## Architecture

OpsBridge has two logical components:

**1. OpsBridge — tunnel lifecycle manager** (this repo)
Manages named SSH reverse tunnels defined in `~/.config/bridge/tunnels.yaml`.
Each tunnel runs in a subprocess with a reconnect backoff loop; PIDs are tracked
in `~/.local/state/bridge/`. Bridge states: `stopped → starting → connected →
degraded → failed`. The `degraded` state means SSH is up but the optional HTTP
health check is failing.

**2. OpsCatalog — operations knowledge repository** (planned extension)
A Git-backed YAML catalog of operations domains, targets, bridges, and actor
classes. OpsBridge consumes this catalog to resolve bridge identifiers and
orient operators. Schema examples are in `wiki/OpsCatalogSpecification.md`.
The catalog layout follows: `opscatalog/domains/<domain>/{domain.yaml,
targets/, bridges/, docs/}`.

Key design constraints:
- OpsBridge owns lifecycle management only; it does not own identity/credentials
- Each tunnel is identified by name (e.g. `state-hub-coulombcore`); names used
  in config, CLI args, and log filenames must stay consistent
- Actor attribution (human operator vs. automation agent) is tracked per bridge
  for audit log traceability (FRS §5.7)

Specification docs are in `wiki/`: PRD (`OpsBridgePrd.md`), FRS
(`OpsBridgeFrs.md`), and OpsCatalog spec (`OpsCatalogSpecification.md`).

## Quick Reference

`~/the-custodian/state-hub/mcp_server/TOOLS.md`