From c1d87b47df2430bf8caff7a05eb67b757eb572b7 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Sat, 2 May 2026 23:17:22 +0200
Subject: [PATCH] Added INTENT.md file

---
 INTENT.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 INTENT.md

diff --git a/INTENT.md b/INTENT.md
new file mode 100644
index 0000000..2a2fc5d
--- /dev/null
+++ b/INTENT.md
@@ -0,0 +1,92 @@
+# INTENT
+
+## Purpose
+
+This repository exists to provide a **reliable, inspectable, and controllable connectivity layer** 
+between distributed dev, build, test and execution environments for dev and ops personal human and agentic.
+
+Its role is to ensure that remote machines can **consistently and safely “phone home”** without requiring complex network infrastructure or manual intervention.
+
+---
+
+## Primary Utility
+
+The repository provides a **managed SSH reverse tunneling system** that:
+
+* Maintains continuous connectivity between remote systems and a central hub
+* Makes connectivity **observable, auditable, and controllable**
+* Exposes this capability as both a **CLI tool and an MCP-accessible service**
+
+It transforms raw SSH port-forwarding into a **first-class operational primitive**.
+
+---
+
+## Intended Users
+
+* Human operators (`adm`) managing infrastructure and connectivity
+* LLM-based agents (`agt`) requiring stable access to local services
+* Deterministic automations (`atm`) coordinating distributed workloads
+
+---
+
+## Strategic Role in the System
+
+This repository acts as the **connectivity backbone** of the custodian ecosystem:
+
+* It enables remote agents and services to participate in a **locally anchored control plane**
+* It decouples **execution location** from **control location**
+* It supports a **hub-and-spoke topology** where the Custodian State Hub remains central
+
+---
+
+## Strategic Boundaries
+
+This repository is **not** intended to:
+
+* Replace SSH as a general-purpose access mechanism
+* Act as a credential authority or security policy engine
+* Provide full network virtualization (e.g., VPN, mesh networking)
+* Host or orchestrate application workloads
+
+Its responsibility ends at **secure, observable, and managed connectivity via tunnels**.
+
+---
+
+## Design Principles
+
+* **Continuity over convenience**
+  Connectivity must persist across failures without manual recovery
+
+* **Observability as a first-class concern**
+  All lifecycle events must be traceable and attributable
+
+* **Actor-aware operations**
+  Every action is tied to a clearly defined actor type (`adm`, `agt`, `atm`)
+
+* **Pluggable security integration**
+  Works with both static keys and external certificate authorities without owning them
+
+* **Toolability**
+  All capabilities should be accessible programmatically (MCP) and operationally (CLI)
+
+---
+
+## Maturity Target
+
+A mature version of this repository should:
+
+* Provide **fully autonomous tunnel lifecycle management** across heterogeneous environments
+* Integrate seamlessly with **centralized access control and certificate systems**
+* Serve as a **standardized connectivity primitive** across all Custodian-managed systems
+* Offer **complete operational transparency** for all connectivity-related actions
+* Be robust enough to act as the **default connectivity layer** for distributed agent systems
+
+---
+
+## Stability Note
+
+Changes to this file represent a **deliberate shift in repository purpose or role** within the system architecture.
+
+Such changes should be rare and made with explicit intent.
+
+