# Unseen Workflow Compiler — Complete Agent Reference

> Turn supplied operational evidence into workflow diagrams with source references. Visual Contract v0.1 validation checks structure; it does not certify factual accuracy.

---

## 1. Executive Mental Model

Use the host to select relevant evidence and collect clarifications, then use Unseen to build and render the workflow. Keep the original sources available so the person using the diagram can check its claims.

Unseen establishes a clean product boundary:
* **The Host Agent** (Cursor, Claude, ChatGPT, Antigravity) handles natural conversation, reads workspace files, and extracts verbatim source evidence.
* **The Unseen Skill** instructs the host how to structure evidence without rewriting it.
* **The Unseen Compiler** performs structural validation, handles host-supplied clarification questions, computes layout, and returns SVG and Mermaid outputs for review.

---

## 2. The Three MCP Compiler Tools

All tools are accessible via Model Context Protocol JSON-RPC 2.0 at `POST /mcp` or local stdio (`npx tsx server/mcp/stdio.ts`).

### Tool 1: `compile_workflow`
**Purpose**: Compiles a `WorkflowEvidenceEnvelope` into a workflow with source references and contract validation.

**Payload Schema**:
```json
{
  "schemaVersion": "0.1",
  "userGoal": "Driver Onboarding and Document Verification SOP",
  "desiredOutput": {
    "orientation": "portrait",
    "depth": "detailed"
  },
  "sources": [
    {
      "id": "s1",
      "locator": "SOP §1.1 (Submission)",
      "excerpt": "Driver submits Aadhaar card, driving license, and bank account details."
    },
    {
      "id": "s2",
      "locator": "SOP §1.2 (Verification)",
      "excerpt": "Compliance manager verifies documents against UIDAI. If check fails, application is rejected."
    }
  ],
  "hostContext": {
    "actors": ["Driver", "Compliance Manager"],
    "contradictions": [],
    "ambiguities": []
  }
}
```

**Return Values**:
* If compilation succeeds (not a factual-completeness guarantee): `{ "status": "ready", "jobId": "wfjob_123", "spec": { ... }, "svg": "<svg>...", "mermaid": "flowchart TD...", "metrics": { ... } }`
* If supplied ambiguities or contradictions remain unresolved: `{ "status": "needs_input", "jobId": "wfjob_123", "questions": [ { "id": "q1", "reason": "source_conflict", "question": "..." } ] }`

---

### Tool 2: `revise_workflow`
**Purpose**: Applies targeted natural language delta corrections to an existing visual without rewriting the entire graph.

**Payload Schema**:
```json
{
  "spec": { ...existing VisualSpec... },
  "instruction": "Change node-2 role to decision and label to 'Aadhaar Verified?'",
  "additionalSources": []
}
```

**Capabilities**:
* Role changes: `step` -> `decision` -> `concept`
* Label updates: Bounded to 35 characters
* Node removal: Removes the selected node and its connected edges; revised output must pass contract validation.
* Connection cleanup: Uses the existing Auto-fix behavior. Inspect any changed relationship against the source; do not assume a visual cleanup proves business order.

---

### Tool 3: `get_workflow`
**Purpose**: Retrieves a previously compiled or cloud-saved workflow by `jobId` or `id`.

**Payload Schema**:
```json
{
  "id": "wfjob_123"
}
```

**Return Values**:
Returns the cached or stored compilation result with full `VisualSpec`, SVG layout, and Mermaid syntax.

---

## 3. The Clarification Loop Pattern

When the host supplies unresolved questions in hostContext.contradictions or hostContext.ambiguities:

1. **Unseen Pauses**: Emits `status: "needs_input"` with explicit `questions`.
2. **Host Inquires**: The agent presents the ambiguity conversationally to the user in chat.
3. **Resumption**: When the user answers, call `compile_workflow` again with the original evidence envelope. Add the following fields to that envelope; this fragment is not a complete request. Each call returns a new `jobId`:
```json
{
  "jobId": "wfjob_123",
  "priorAnswers": [
    {
      "questionId": "q_contra_1",
      "answer": "Manager approval applies under $500. VP review applies for $500 and above.",
      "source": "user"
    }
  ]
}
```
Unseen adds the supplied answer and its declared origin to the evidence context and attempts compilation. Successful output has `status: "ready"`.

---

## 4. Visual Contract v0.1 Bounds

To ensure every generated visual is legible on mobile and desktop without cognitive overload:
* **Max Nodes**: 12 nodes per macro flowchart.
* **Max Edges**: 24 edges per flowchart.
* **Max Sources**: 60 evidence chunks per document.
* **Node Roles**: `step` (action), `decision` (branching condition), `concept` (data/entity).
* **Decision Branches**: Every edge leaving a decision needs a source-supported label. A missing outcome is an evidence gap; do not invent a second branch to satisfy a layout warning.
* **Layout**: Content-aware sizing preserves labels and details. Inspect dense diagrams and exports for readability.

---

## 5. Multi-Host Installation

* **Cursor**: Add to `.cursor/mcp.json` with command `npx tsx server/mcp/stdio.ts`.
* **Claude Code**: Run `claude mcp add unseen -- npx tsx server/mcp/stdio.ts`.
* **Antigravity**: Project-local skill detected automatically in `.agents/skills/unseen/SKILL.md`.
* **ChatGPT / Actions**: Import OpenAPI spec from `/api/openapi.json`.