From 482edcd7ebba457a09773f0f33ddc39d810a7293 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Wed, 11 Mar 2026 21:34:37 +0100
Subject: [PATCH] chore: register with Custodian State Hub

Add CLAUDE.md (session protocol, tool boundary, workplan prefix BRIDGE-WP)
and workplans/ directory. Repo registered as ops-bridge under custodian
domain (id: 1bf99f56).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2177798
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,81 @@
+# ops-bridge — Claude Code Instructions
+
+**Purpose:** SSH reverse tunnel lifecycle manager. Keeps remote execution
+environments (COULOMBCORE, Railiance nodes) connected to the local Custodian
+State Hub so Claude Code sessions on those machines have full MCP connectivity.
+
+**Domain:** custodian
+**Repo slug:** ops-bridge
+**Repo ID:** 1bf99f56-6e94-4379-a9ea-295a4c181889
+
+## Custodian State Hub Integration
+
+State Hub: http://127.0.0.1:8000
+
+### Session Protocol
+
+**Step 1 — Orient**
+```
+get_domain_summary("custodian")
+```
+
+**Step 2 — Scan workplans**
+```
+ls workplans/
+```
+
+**During work:** use `record_decision()`, `add_progress_event()`, `resolve_decision()`.
+
+**Session close:** `add_progress_event()` with workstream_id.
+
+If workplan files were modified, run from `~/the-custodian/state-hub/`:
+```bash
+make fix-consistency REPO=ops-bridge
+```
+
+### Workplan Convention (ADR-001)
+
+File location: `workplans/BRIDGE-WP-NNNN-<slug>.md`
+Prefix: `BRIDGE-WP`
+
+## What this repo builds
+
+A CLI tool (`bridge`) that manages named SSH reverse tunnels:
+
+```
+bridge up [TUNNEL]      # start tunnel(s)
+bridge down [TUNNEL]    # stop tunnel(s)
+bridge restart [TUNNEL] # restart tunnel(s)
+bridge status           # show all tunnels: state, uptime, last health check
+bridge logs [TUNNEL]    # tail reconnect log
+```
+
+Config file: `~/.config/bridge/tunnels.yaml`
+
+Each tunnel:
+- Named (e.g. `state-hub-coulombcore`)
+- Reverse SSH port-forward: `ssh -R remote_port:127.0.0.1:local_port host`
+- Auto-reconnects on drop (backoff loop)
+- Optional HTTP health check to confirm the forwarded service is reachable
+
+PRD: `workplans/BRIDGE-WP-0001-initial-implementation.md`
+
+## Stack
+
+- **Language:** Python 3.11+
+- **CLI framework:** Typer
+- **Dependencies:** typer, pyyaml, httpx
+- **Packaging:** `uv tool install` (single command install, no venv activation)
+- **No system daemons** — process management is internal, PID tracked in
+  `~/.local/state/bridge/`
+
+## Repo boundary
+
+This repo owns **tunnel lifecycle management only**. It does not own:
+- State hub code → `the-custodian/state-hub/`
+- SSH key management → `railiance-infra/` (S1) or user dotfiles
+- Ansible/provisioning → `railiance-infra/`
+
+## Quick Reference
+
+`~/the-custodian/state-hub/mcp_server/TOOLS.md`