converge-remote 0.1.2

# Converge: Semantic Governance & Alignment

> Converge is a vision for **semantic governance**. We move from fragmented intent to unified, converged states through a deterministic alignment engine. Our mission is to provide a stable foundation for complex decision-making where human authority and AI agency coexist in a transparent, explainable ecosystem.

## Converge Remote

Converge Remote is a gRPC client that connects to [converge-runtime](https://github.com/kpernyer/converge-runtime) for multi-actor, collaborative convergence. It implements the [Converge Protocol](https://github.com/kpernyer/converge-ios/blob/main/CROSS_PLATFORM_CONTRACT.md) for streaming facts and control messages.

## Architecture

```text
┌─────────────────────┐         ┌─────────────────────┐
│  converge-remote    │  gRPC   │  converge-runtime   │
│  (this project)     │◄───────►│  (server)           │
└─────────────────────┘ Stream  └─────────────────────┘
```

**When to use converge-remote vs converge:**

| App               | Engine Location | Use Case                                   |
| ----------------- | --------------- | ------------------------------------------ |
| `converge`        | In-process      | Local dev, testing, single-user, offline   |
| `converge-remote` | Server          | Multi-actor, collaboration, persistence    |

## Installation

```bash
cargo install converge-remote
```

Or build from source:

```bash
git clone https://github.com/kpernyer/converge-remote.git
cd converge-remote
cargo build --release
```

## Usage

### Run a Job

```bash
# Connect to runtime and run a convergence job
converge-remote run --template growth-strategy --server grpc://localhost:50051

# With seeds
converge-remote run --template growth-strategy \
  --seeds '[{"id": "context", "content": "B2B SaaS startup"}]' \
  --server grpc://localhost:50051

# Stream facts as they arrive
converge-remote run --template growth-strategy --stream

# JSON output
converge-remote run --template growth-strategy --json
```

### Watch a Running Job

```bash
# Subscribe to job status updates
converge-remote watch <run_id> --server grpc://localhost:50051
```

### Inject Facts (Human-in-the-Loop)

```bash
# Add a fact to a running job
converge-remote inject --run-id <id> \
  --fact '{"key": "Seeds", "id": "user-input", "content": "Additional context"}'
```

### Control Commands

```bash
# Approve a pending proposal
converge-remote approve <proposal_id> --run-id <id>

# Reject with reason
converge-remote reject <proposal_id> --run-id <id> --reason "Not applicable"

# Pause/resume convergence
converge-remote pause <run_id>
converge-remote resume <run_id>

# Cancel a job
converge-remote cancel <job_id> --reason "No longer needed"
```

### Query Capabilities

```bash
# Get server capabilities
converge-remote capabilities --server grpc://localhost:50051
```

## Configuration

Set the server address via environment variable:

```bash
export CONVERGE_SERVER=grpc://localhost:50051
converge-remote run --template growth-strategy
```

Or use a `.env` file:

```env
CONVERGE_SERVER=grpc://production.converge.zone:50051
```

## Exit Codes

| Code | Meaning                            |
| ---- | ---------------------------------- |
| 0    | Converged successfully             |
| 1    | Halted (invariant violated)        |
| 2    | Budget exhausted                   |
| 3    | Error (connection, system failure) |

## Documentation

- **Knowledgebase:** See [converge-business/knowledgebase/](../converge-business/knowledgebase/)
- **Cross-Platform Contract:** See [converge-business/knowledgebase/android-CROSS_PLATFORM_CONTRACT.md](../converge-business/knowledgebase/android-CROSS_PLATFORM_CONTRACT.md) (Shared contract)
- **Collaboration:** See [COLLABORATION.md](COLLABORATION.md)
- **For LLMs:** See [AGENTS.md](AGENTS.md)

### Proto Definitions

The gRPC services are defined in `proto/converge.proto`:

- `ContextService` - Watch facts, append entries, control jobs
- `JobService` - Create, list, cancel jobs
- `CapabilityService` - Query server capabilities

## Development

### Running Tests

```bash
# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run integration tests (requires live runtime)
cargo test --features integration
```

### Code Coverage

```bash
# Install coverage tools
cargo install cargo-llvm-cov
rustup component add llvm-tools-preview

# Generate coverage report
./scripts/coverage.sh

# Generate and open in browser
./scripts/coverage.sh --open
```

### Code Quality

```bash
# Format code
cargo fmt

# Run linter
cargo clippy --all-targets --all-features

# Security audit
cargo audit
```

### CI Pipeline

The CI pipeline runs automatically on push and PR:

| Check            | Description                                   |
| ---------------- | --------------------------------------------- |
| Code Quality     | Clippy lints + Rustfmt formatting             |
| Build            | Debug + Release builds (stable + beta)        |
| Tests + Coverage | 186+ tests with llvm-cov coverage             |
| Documentation    | rustdoc build with warnings as errors         |
| Security Audit   | cargo-audit for vulnerability scanning        |
| Cross-platform   | Build verification on Linux, macOS, Windows   |

## Related Projects

| Project | Purpose |
| ------- | ------- |
| [converge-runtime](https://github.com/kpernyer/converge-runtime) | Server that runs the convergence engine |
| [converge-application](https://github.com/kpernyer/converge-application) | Standalone CLI/TUI (in-process engine) |
| [converge-core](https://github.com/kpernyer/converge-core) | Core convergence engine |
| [converge-ios](https://github.com/kpernyer/converge-ios) | iOS mobile client |

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Development Tools

This project is built with the help of modern AI-assisted development tools:

### Agent Tooling (Examples)

This project supports a **tool-agnostic agent workflow**. Claude, Codex, Gemini, Cursor, and similar tools are optional frontends; the shared contract is visible task state, scoped changes, validation, and explicit handoffs.

- **[Claude Code](https://claude.ai/claude-code)** - Example interactive coding agent
- **[Cursor](https://cursor.com)** - Example AI-powered IDE workflow
- **[Antigravity](https://antigravity.dev)** - Example AI pair-programming tool
- **Frontier models (Claude / Gemini / others)** - Use any provider that fits the task and team policy

### Version Control & Task Tracking

- **[Jujutsu (jj)](https://github.com/martinvonz/jj)** - Use jj on top of Git for day-to-day version control (commit/diff/rebase/undo)
- **Task tracking (tool-agnostic)** - Use GitHub Issues, Jira, Linear, or a repo-local `TASKS.md`

```bash
# Quick workflow (agent-friendly)
jj status                 # See changes
jj diff                   # Review changes
jj commit -m "message"    # Commit
jj git push               # Push via git remote
# Update tracker or TASKS.md with status + handoff
```

### Key Rust Crates

| Crate | Purpose |
|-------|---------|
| `tokio` | Async runtime |
| `axum` | HTTP framework |
| `serde` / `serde_json` | Serialization |
| `thiserror` | Error handling |
| `tracing` | Structured logging |
| `rayon` | Parallel computation |
| `proptest` | Property-based testing |
| `burn` | ML/deep learning (converge-llm) |
| `tonic` / `prost` | gRPC support |