@jbaehova/onthego 0.1.2 → 0.1.3

package/README.md

@@ -1,20 +1,68 @@
-# ONTHEGO
+<h1 align="center">ONTHEGO</h1>
 
-ONTHEGO carries project-scoped agent sessions, a redacted handoff, execution logs, and work state between a local Git workspace and a Daytona sandbox. A small control plane on Contabo keeps the latest state available across local machines. `status` turns the synchronized state into a concise update with GPT-5.6 Luna using high reasoning effort.
+<p align="center">
+  <strong>Carry the work. Keep the context.</strong>
+</p>
 
-## Install
+<p align="center">
+  <em>Secure, project-scoped AI agent handoffs from your local Git workspace to a Daytona sandbox.</em>
+</p>
 
-The npm package currently uses the `@jbaehova` scope because the unscoped `onthego` name is owned by another npm account.
+<p align="center">
+  <img alt="npm version" src="https://img.shields.io/npm/v/%40jbaehova%2Fonthego?style=flat-square&logo=npm&logoColor=white&color=CB3837">
+  <img alt="Node 18+" src="https://img.shields.io/badge/Node-18%2B-43853D?style=flat-square&logo=node.js&logoColor=white">
+  <img alt="Go 1.25.4+" src="https://img.shields.io/badge/Go-1.25.4%2B-00ADD8?style=flat-square&logo=go&logoColor=white">
+  <img alt="macOS arm64 and Linux x64" src="https://img.shields.io/badge/Platform-macOS_arm64_%7C_Linux_x64-334155?style=flat-square">
+  <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/License-MIT-C5A800?style=flat-square"></a>
+</p>
 
-```sh
+<p align="center">
+  <img src="assets/onthego-banner.webp" alt="ONTHEGO carrying secure agent context from a local workspace to a cloud sandbox" width="88%">
+</p>
+
+Your repository moves easily. Agent memory does not.
+
+ONTHEGO finds the Codex, Cursor, Hermes, and Claude sessions that belong to the current Git project, removes common secrets on your machine, creates a focused handoff, and sends it to an isolated Daytona workload. Run status is synchronized through a lightweight control plane. Results come back only after their SHA-256 digest matches the remote receipt.
+
+```text
+local project  ->  redact  ->  HANDOFF.md  ->  Daytona  ->  verify  ->  local result
+```
+
+## What It Does
+
+- Discovers every supported agent session associated with the current Git repository.
+- Redacts tokens, authorization headers, private keys, and matching secret assignments before transfer.
+- Generates a redacted context envelope and human-readable `HANDOFF.md`.
+- Starts the default `agent-sync` workload in Daytona with one command.
+- Synchronizes run state, redacted logs, and summaries across authenticated devices.
+- Uses GPT-5.6 Luna with high reasoning effort to turn current state into a concise status update.
+- Downloads an artifact only after its hash matches the remote run receipt.
+
+## Quick Start
+
+Install the CLI:
+
+```bash
 npm install -g @jbaehova/onthego
 ```
 
-The installed command is `onthego`.
+Create a private `.env` at the Git root:
+
+```dotenv
+DAYTONA_API_KEY=...
+ONTHEGO_CONTROL_PLANE_URL=https://your-control-plane.example.com
+ONTHEGO_CONTROL_PLANE_TLS_SHA256=...
+ONTHEGO_LOGIN_BOOTSTRAP_TOKEN=...
+
+# Optional. Enables the LLM summary in `onthego status`.
+OPENAI_API_KEY=...
+```
+
+Lock down the file, then run the five-command flow:
 
-## Phase 1 commands
+```bash
+chmod 600 .env
 
-```sh
 onthego init
 onthego login
 onthego pass
@@ -22,48 +70,143 @@ onthego status
 onthego pull
 ```
 
-`init` turns the current Git repository into an ONTHEGO project. It creates the safe, trackable `.onthego.yaml` project identity and adds local secret and state patterns to `.gitignore`. Re-running it preserves the existing project identity. `login` authenticates this device with the ONTHEGO control plane. `pass` automatically finds every session for the current Git project from Codex, Cursor, Hermes, and Claude. It redacts all detected sessions, generates `HANDOFF.md`, and starts the default `agent-sync` workload in Daytona. No agent or session option is required. `status` refreshes the latest Daytona run and redacted logs, synchronizes them through the control plane, and generates the LLM summary. `pull` downloads the latest result only after its SHA-256 hash matches the remote receipt.
+That is the complete Phase 1 workflow. You do not choose an agent or paste a session ID. `onthego pass` resolves the current Git root and collects the matching sessions automatically.
+
+> [!NOTE]
+> The current release expects a Daytona account and a deployed ONTHEGO control plane. The control plane server is included in this repository. See [Architecture](docs/architecture.md) and the [Contabo operations guide](docs/contabo.md).
 
-Run `onthego init` once after cloning or creating a repository. The Phase 1 pass flow is always `onthego pass`.
+## The Five Commands
 
-## Secrets
+| Command | Purpose |
+| --- | --- |
+| `onthego init` | Register the current Git repository, create its stable `.onthego.yaml` identity, and add local-only paths to `.gitignore`. |
+| `onthego login` | Authenticate this device with the ONTHEGO control plane. |
+| `onthego pass` | Collect project sessions, redact them locally, create the handoff, and start `agent-sync` in Daytona. |
+| `onthego status` | Refresh the latest Daytona run and redacted logs, synchronize state, and generate a concise summary. |
+| `onthego pull` | Download the latest result after receipt and SHA-256 verification. |
 
-All repository secret values live in one root `.env`. ONTHEGO searches from the working directory to the Git root and refuses a file readable by group or other users. The current integration reads these keys:
+Every public command supports schema-versioned JSON output:
 
-- `DAYTONA_API_KEY`
-- `OPENAI_API_KEY`
-- `ONTHEGO_CONTROL_PLANE_URL`
-- `ONTHEGO_CONTROL_PLANE_TLS_SHA256`
-- `ONTHEGO_LOGIN_BOOTSTRAP_TOKEN`
-- `ONTHEGO_CONTROL_PLANE_SIGNING_KEY`
-- `CONTABO_VPS_IP_ADDRESS`
-- `CONTABO_VPS_DEFAULT_USER`
-- `CONTABO_VPS_PASSWORD`
+```bash
+onthego status --json
+onthego pull --output ./handoff-result.md --json
+```
 
-The `.env` file, `AGENTS.md`, `.agents/`, local state, npm credentials, archives, build output, logs, and editor metadata are ignored by Git. The login session is stored outside the repository with permission `0600`.
+## How It Works
+
+```mermaid
+flowchart LR
+    A[Codex] --> E[Project session discovery]
+    B[Cursor] --> E
+    C[Hermes] --> E
+    D[Claude] --> E
+    E --> F[Local redaction]
+    F --> G[Context envelope and HANDOFF.md]
+    G --> H[Daytona agent-sync]
+    H --> I[Redacted logs and run receipt]
+    I --> J[ONTHEGO control plane]
+    J --> K[Authenticated devices]
+    I --> L[SHA-256 verified pull]
+```
 
-## Security model
+### 1. Scope by project
 
-- Context selection accepts only Codex, Cursor, Hermes, and Claude sessions associated with the current Git project.
-- Redaction removes common tokens, authorization headers, private keys, and matching secret assignments before transfer.
-- The Contabo client pins the server certificate SHA-256 fingerprint.
-- Control plane state updates use authenticated generation checks.
-- Daytona result files are accepted only when the remote receipt contains a matching SHA-256 hash.
-- Portable internal snapshots use age X25519 encryption and Ed25519 signatures.
+ONTHEGO uses the Git root as the trust and discovery boundary. It scans the local storage used by Codex, Cursor, Hermes, and Claude, then keeps only sessions associated with that project.
 
-## Release
+### 2. Redact before transfer
 
-GitHub Actions tests the Go code, builds static Linux amd64 and macOS arm64 binaries, assembles the npm package, scans the release tree for local or secret files, publishes to npm, and attaches checksummed binaries to the GitHub release.
+Raw sessions stay local. Before an envelope leaves the machine, ONTHEGO filters common API keys, bearer tokens, private keys, secret assignments, and opaque encrypted agent payloads. The envelope records source hashes and byte ranges so the handoff remains auditable without exposing local paths.
 
-## Development
+### 3. Run in isolation
+
+The official Daytona Go SDK creates or selects a sandbox, uploads the redacted context, and starts an ONTHEGO-owned process session. The default CPU-only `agent-sync` workload returns `HANDOFF.md` and can be replaced with a project-defined workload in `.onthego.yaml`.
+
+### 4. Resume with proof
+
+`onthego status` combines local Git state with remote run state. `onthego pull` refuses results with a missing or mismatched SHA-256 receipt, so an unverified artifact never becomes the local handoff.
+
+## Security Model
+
+| Boundary | Protection |
+| --- | --- |
+| Project | Session discovery is limited to the current Git repository. |
+| Secrets | The root `.env` must not be accessible by group or other users and is never tracked. |
+| Transfer | Session content is redacted locally before upload. |
+| Control plane | TLS is pinned by certificate SHA-256 fingerprint. |
+| State | Authenticated generation checks reject stale writes. |
+| Results | Remote artifacts are accepted only when their SHA-256 hash matches the receipt. |
+| Snapshots | Portable `.otg` snapshots use age X25519 encryption and Ed25519 signatures. |
 
-Go 1.25.4 or newer and Node.js 18 or newer are required.
+`onthego init` always keeps `AGENTS.md`, `.agents/`, `.env`, `.onthego.local/`, `HANDOFF.md`, and `*.otg` out of Git. Device login sessions are stored outside the repository with `0600` permissions.
 
-```sh
+## Project Configuration
+
+`onthego init` creates a safe, trackable `.onthego.yaml`. It contains the project identity and workload policy, never secret values. Re-running `init` preserves the existing project ID.
+
+The default workload is deliberately small:
+
+```yaml
+workloads:
+  agent-sync:
+    kind: agent
+    image: debian:bookworm-slim
+    gpu_count: 0
+    argv:
+      - /bin/sh
+      - -lc
+      - cp ../context/HANDOFF.md ./HANDOFF.md
+    output_path: HANDOFF.md
+    timeout_seconds: 600
+```
+
+The CLI reads `.env` from the current directory up to the Git root. Existing process environment values take precedence over file values. Daytona also accepts `DAYTONA_JWT_TOKEN` as an alternative to `DAYTONA_API_KEY`.
+
+## Platform Support
+
+The npm package currently ships prebuilt binaries for:
+
+- macOS on Apple silicon (`darwin-arm64`)
+- Linux on x86-64 (`linux-x64`)
+
+Node.js 18 or newer is required for the npm launcher. Building from source requires Go 1.25.4 or newer.
+
+## Development
+
+```bash
+git clone https://github.com/jbaehova/onthego.git
+cd onthego
 make check
 make build
 ```
 
-GPU fine-tuning, GPU model serving, and the Hugging Face connector are backlog items. Their internal experiments are not part of the Phase 1 command contract.
+Useful project commands:
+
+```bash
+make test
+./scripts/demo.sh
+go run ./cmd/onthego --help
+go run ./cmd/onthego-server
+```
+
+The release workflow tests and vets the Go code, builds static Linux amd64 and macOS arm64 binaries, scans the npm package for local or secret files, publishes with npm provenance, and attaches checksummed binaries to the GitHub release.
+
+## Repository Layout
+
+```text
+cmd/                  CLI and control plane entry points
+internal/             capture, redaction, transport, state, and verification
+npm/                  cross-platform npm launcher and packaged binaries
+deploy/contabo/       hardened systemd service for the control plane
+docs/                 architecture, demo, pitch, and progress notes
+scripts/              local demo workflow
+```
+
+## Roadmap
+
+The five-command agent handoff is the supported Phase 1 contract. GPU fine-tuning, GPU model serving, and Hugging Face model and dataset connectors are active backlog items and are not presented as production features yet.
+
+Follow the implementation record in [docs/progress.md](docs/progress.md).
+
+## License
 
-See [docs/architecture.md](docs/architecture.md) and [docs/progress.md](docs/progress.md) for the implementation record.
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbaehova/onthego",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Carry agent context and work between local projects and Daytona sandboxes",
   "license": "MIT",
   "repository": {