> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connector Integration

> How MonoSurf connects to connector.json for machine-readable workflow orchestration.

# Connector Integration

MonoSurf is a CLI binary. connector.json defines how CLI binaries are invoked. They connect naturally.

## The Pattern

```
┌──────────────────────────────────────────────────────────────────┐
│  connector.json (defines)                                        │
│  "To search X, run monosurf x.com search {query} --json"         │
│  "If results > 3 lines, suggest: read specific tweet"            │
│  "If write intent, require approval gate"                        │
├──────────────────────────────────────────────────────────────────┤
│  cjson runner (executes)                                         │
│  Reads connector.json → resolves variables → runs binary         │
│  Matches output → suggests next action                           │
├──────────────────────────────────────────────────────────────────┤
│  monosurf (does the work)                                        │
│  Connects to Chrome → navigates → extracts → returns             │
└──────────────────────────────────────────────────────────────────┘
```

## Intent Field

connector.json v2.1 adds `intent` to StepDefinition:

```json theme={null}
"search": {
  "binary": "monosurf",
  "args": ["x.com", "search", "{query}", "--json"],
  "intent": "read",
  "output": {
    "has_results": {
      "match": "lines_over:3",
      "next": ["read specific tweet", "check author timeline"]
    }
  }
},
"post": {
  "binary": "monosurf",
  "args": ["x.com", "post", "{text}"],
  "intent": "write"
}
```

* `intent: "read"` — safe, AI can execute freely within grant
* `intent: "write"` — mutates state, cjson runner prompts for confirmation

This field was added to the connector.json schema specifically for the MonoSurf use case, but applies to any tool that has read and write operations.

## Pipeline Example

A connector.json can define a full discover → dive → engage pipeline:

```
Phase 1: discover
  monosurf x.com search "AI terminal" --json
  → output matched "has_results"
  → next: "read specific tweet"

Phase 2: dive
  monosurf x.com read {selected_url} --json
  → output matched "has_thread"
  → next: "reply to tweet"

Phase 3: engage (gated)
  [APPROVAL GATE] "All write operations must be confirmed"
  → User approves
  monosurf x.com post {text}
  → "posted"
```

Machine executes steps 1-2 automatically. Step 3 pauses for human approval.
This is the same separation pattern as NIIA's read-only observe surface and
OTP-gated control surface over Kernel CLI.

## Same Pattern, Every Tool

connector.json doesn't know or care that MonoSurf uses Chrome CDP internally. It sees a CLI binary with arguments and output. The same connector.json format works for:

| Tool      | Transport         | connector.json sees   |
| --------- | ----------------- | --------------------- |
| monosurf  | chromiumoxide CDP | `binary: "monosurf"`  |
| monofetch | HTTP              | `binary: "monofetch"` |
| monogit   | Git API           | `binary: "monogit"`   |
| niia      | Local CLI         | `binary: "niia"`      |

One format. Any tool. The transport is the tool's problem, not the orchestrator's.

## Running via cjson

```bash theme={null}
# List available steps
cjson monosurf-x.connector.json --list

# Run single step
cjson monosurf-x.connector.json --step search query="rust"

# Run full pipeline
cjson monosurf-x.connector.json topic="AI agents"
```

The cjson runner:

1. Loads connector.json
2. Resolves `{variables}` from CLI arguments
3. Executes binary with args
4. Matches output against rules
5. Suggests next actions
6. Gates write operations with approval prompts