# Unseen Workflow Compiler — Complete Agent Reference

> Turn supplied operational evidence into workflow diagrams with source references.

> For agents: connect to https://unseendocs.in/mcp/oauth with OAuth and have the user approve the connection in a browser. Product and capability guide: https://unseendocs.in/llms.txt. Human setup page: https://unseendocs.in/agents.

---

## 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 — including the text and arrow order of embedded process diagrams, which Unseen cannot see unless the host sends them. If an image cannot be read, the host tells the user what was left out.
* **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 Eleven MCP Compiler, Feedback & Account Tools

Connect new clients to `POST /mcp/oauth` using Streamable HTTP. The host carries its OAuth access token in the HTTP Authorization header. MCP initialization returns server instructions, and the host can discover tools, prompts, and resources through the protocol. The domain also serves [Skill discovery](https://unseendocs.in/.well-known/agent-skills/index.json) and the [Workflow Compiler Skill](https://unseendocs.in/skills/unseen-workflow-compiler/SKILL.md).

The compatibility routes `/mcp/chatgpt` and `/mcp` remain available for existing clients. The in-band login tools are specific to legacy `/mcp`. Legacy `/mcp` offers public initialization, tool and resource discovery, and `send_feedback`. Workflow and account tools require verified sign-in. Local stdio remains available for local setups. Once signed in, rendering a supplied `{ spec }`, `revise_workflow`, and `autofix_workflow` use zero Unseen credits. The host AI provider's own usage still applies.

### Tool 1: `compile_workflow`
**Purpose**: Compiles a workflow diagram with verbatim source references, orthogonal vector `svg`, hosted `svgUrl` (`/api/share/<token>/svg`), `mermaid`, `excalidraw` scene, interactive owner-bound `studioUrl` (`/s/<token>`), typed `findings`, `checksApplied`, and `nextActions`. Supports `renderFormat` (`"full" | "preview" | "compact" | "svg" | "mermaid"`) and `evidenceCoverage` preflight reporting.

**Three Input Modes**:
1. **Host-LLM Native Mode ($0 Unseen credits, verified account required for hosted MCP)**: Synthesize `VisualSpec` v0.1 JSON using your own host LLM and pass `{ "spec": { "schemaVersion": "0.1", "kind": "flowchart", "title": "...", "summary": "...", "sources": [...], "nodes": [...], "edges": [...] }, "evidenceCoverage": { ... } }`. Outgoing edges from `decision` nodes must carry a source-backed `label`. Unseen deterministically validates citations, heals connectors, and renders `svg`, `svgUrl`, `mermaid`, `excalidraw`, and owner-bound `studioUrl` (`/s/<token>`) at 0 Unseen credits (returning exact `missingAreas` validation errors + `errorKind` for instant self-correction).
2. **Raw Text Mode**: Pass `{ "text": "..." }` and Unseen auto-segments into `sources[]` and compiles via Unseen's AI pipeline.
3. **Structured Evidence Envelope Mode**:
```json
{
  "schemaVersion": "0.1",
  "userGoal": "Driver Onboarding and Document Verification SOP",
  "desiredOutput": {
    "orientation": "portrait",
    "depth": "detailed",
    "swimlane": true
  },
  "sources": [
    {
      "id": "s1",
      "locator": "SOP §1.1 (Submission)",
      "excerpt": "Driver submits Aadhaar card, driving license, and bank account details.",
      "modality": "text",
      "confidence": "verbatim"
    },
    {
      "id": "s2",
      "locator": "SOP §1.2 (Verification)",
      "excerpt": "Compliance manager verifies documents against UIDAI. If check fails, application is rejected."
    }
  ],
  "evidenceCoverage": {
    "pagesExamined": 2,
    "totalPages": 2,
    "textExtracted": true,
    "embeddedDiagramsDetected": 0,
    "omittedMedia": []
  },
  "hostContext": {
    "actors": ["Driver", "Compliance Manager"],
    "contradictions": [],
    "ambiguities": []
  }
}
```

**Return Values**:
* If compilation succeeds (present the visual to the user): `{ "status": "ready", "jobId": "wfjob_123", "spec": { ... }, "svg": "<svg>...", "svgUrl": "https://unseendocs.in/api/share/shr_.../svg", "mermaid": "flowchart TD...", "excalidraw": { ... }, "studioUrl": "https://unseendocs.in/s/shr_...", "checksApplied": [...], "nextActions": [...], "findings": [...], "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` (No Credits, Sign-In Required, Deterministic)
**Purpose**: Applies targeted node label/role changes, node removals, or connection cleanup to an existing `VisualSpec` without rewriting the entire graph ($0 credits once signed in).

**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.

---

### Tool 4: `autofix_workflow` (No Credits, Sign-In Required, Idempotent)
**Purpose**: Deterministic connector healing and full visual re-rendering (0 credits; remote calls need a signed-in user). Rescues orphan nodes, heals broken decision branches, recomputes orthogonal layout, and returns fresh `spec`, `svg`, `mermaid`, `excalidraw`, and `studioUrl`.

**Visual Editing Guidance**:
* **Cosmetic / Styling Edits**: Edit the returned `<svg>` XML directly (colors, stroke widths, callout annotations, font styling).
* **Structural / Topological Edits**: Modify `spec.nodes` or `spec.edges` in the `VisualSpec` JSON and call `autofix_workflow` to deterministically route connectors and re-render `svg`, `mermaid`, `excalidraw`, and `studioUrl` at $0 cost.

---

### Tool 5: `enhance_workflow` (Bundled Free TypeSafe Jev Semantic Audit & Repair)
**Purpose**: Audits `spec` against its cited `sources[]` using TypeSafe Jev for unsupported claims, missing decision branches, and role accuracy, applies targeted repair if actionable findings exist, and returns enhanced `spec`, `svg`, `mermaid`, `excalidraw`, and `studioUrl`.

---

### Tool 6: `detect_workflows` (Read-Only)
**Purpose**: Segments multi-procedure documents or raw `text` into candidate workflows (`id`, `title`, `description`, `sourceIds`) audited by TypeSafe Jev.

---

### Tool 7: `get_account_status` (Read-Only)
**Purpose**: Returns the authenticated user's plan, `creditsBalance`, `freeGenerationsRemaining`, `maxDocumentPages` (up to 100 pages per visual), and 1-click prepaid `refillUrl` (`https://unseendocs.in/#pricing`).

---

### Tools 8–10: Legacy authentication on `/mcp` (`auth_request_otp`, `auth_verify_otp`, `auth_login`)
* **`auth_request_otp`**: Sends a 6-digit Login OTP (`UNSEEN_LOGIN_OTP`) to `email`.
* **`auth_verify_otp`**: Verifies `email` + 6-digit `otp` and returns `{ token: "utok_...", user }` for `Authorization: Bearer <token>` or `authToken`.
* **`auth_login`**: Authenticates an existing password account on the legacy endpoint. For new hosted setups, approve the connection in the browser.

---

### Tool 11: `send_feedback` (Free)
**Purpose**: Records structured agent or user workflow quality feedback (`category`: `"bug" | "dx_friction" | "accuracy" | "feature_request" | "layout"`, `message`, optional `tool`). Privacy invariant: never include raw SOP excerpts or personal data in feedback payloads.

---

## 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

The bounded contract limits diagram size:
* **Max Nodes**: Up to 60 flow nodes (`step`, `decision`, `concept`) plus up to 60 typed supporting rules (`ruleKind` + `appliesTo`) per diagram.
* **Max Edges**: Up to 240 edges per flowchart.
* **Max Sources**: Up to 60 evidence chunks per document (up to 2000 characters each).
* **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. Hosted MCP setup

Use `https://unseendocs.in/mcp/oauth` and approve the connection in your browser. In a custom MCP client, choose Streamable HTTP and OAuth.

- **ChatGPT:** In [ChatGPT Plugins](https://chatgpt.com/plugins), choose Add custom MCP server and paste the endpoint. Account and workspace rules apply.
- **Claude:** In Settings → Connectors, add a custom connector and paste the endpoint. Check [plan and workspace requirements](https://support.anthropic.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).
- **Gemini:** In Settings → Connected Apps → Custom apps, add the endpoint and sign in. See [Gemini setup and account requirements](https://support.google.com/gemini/answer/17209137).
- **Browser-capable agent:** Use Unseen's `compile_workflow` MCP tool when available. If you can't use MCP, open [Unseen](https://unseendocs.in/) and use the ordinary website sign-in.

### WhatsApp and personal agents

- [Instinct](https://unseendocs.in/agents?host=instinct&format=md), [Muse](https://unseendocs.in/agents?host=muse&format=md), [OpenClaw](https://unseendocs.in/agents?host=openclaw&format=md), [Hermes Agent](https://unseendocs.in/agents?host=hermes&format=md), [OpenAI Dot](https://unseendocs.in/agents?host=dot&format=md), [Grok Bot](https://unseendocs.in/agents?host=grok-bot&format=md).
- **Personal agent prompt:**

Turn my SOP into a source-cited flowchart with Unseen. If I haven't provided the document, ask me to attach or paste it.

Use Unseen's MCP tool compile_workflow first. If it isn't connected and your host supports remote MCP, use https://unseendocs.in/mcp/oauth and follow https://unseendocs.in/llms-full.txt. Ask before changing settings and let me approve sign-in.

Send the actual flowchart here as an SVG or PNG attachment, or send the returned svgUrl if you can't attach it. Include the returned studioUrl when available.

Use a browser to make the visual only if you can't use MCP. Open https://unseendocs.in/ and pause for sign-in if needed. Export the visual, or create a link from Share Visual with my approval. Return the file or link, never a screenshot of your computer.

### Additional clients and developer tools

**Codex CLI:** Run both commands and finish sign-in in your browser.

```sh
codex mcp add unseen --url https://unseendocs.in/mcp/oauth
codex mcp login unseen
```

Or merge this into ~/.codex/config.toml (or .codex/config.toml) and run `codex mcp login unseen`.

```toml
[mcp_servers.unseen]
url = "https://unseendocs.in/mcp/oauth"
```

**Claude Code:** Run `claude mcp add --transport http unseen https://unseendocs.in/mcp/oauth`, then use `/mcp` in Claude Code to sign in.

**Gemini CLI:** Run `gemini mcp add --transport http unseen https://unseendocs.in/mcp/oauth`, then use `/mcp auth unseen` in Gemini CLI to sign in.

**Cursor:** Merge into `.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "unseen": {
      "url": "https://unseendocs.in/mcp/oauth"
    }
  }
}
```

**VS Code:** Merge into `.vscode/mcp.json` and use Copilot Chat in Agent Mode.

```json
{
  "servers": {
    "unseen": {
      "type": "http",
      "url": "https://unseendocs.in/mcp/oauth"
    }
  }
}
```

**Zed:** Merge into `~/.config/zed/settings.json`.

```json
{
  "context_servers": {
    "unseen": {
      "url": "https://unseendocs.in/mcp/oauth"
    }
  }
}
```

**Devin Desktop (formerly Windsurf):** Run in the Devin CLI and approve the connection in your browser.

```sh
devin mcp add unseen https://unseendocs.in/mcp/oauth
devin mcp login unseen
```

**Grok Build:** Run `grok mcp add --transport http unseen https://unseendocs.in/mcp/oauth`. Grok Build opens sign-in on first use.

**OpenCode v2:** Run `opencode mcp add unseen --url https://unseendocs.in/mcp/oauth && opencode mcp auth unseen`, or merge this into your OpenCode config and run `opencode mcp auth unseen`.

```json
{
  "mcp": {
    "servers": {
      "unseen": {
        "type": "remote",
        "url": "https://unseendocs.in/mcp/oauth"
      }
    }
  }
}
```

Antigravity and Continue use legacy `/mcp`. See Tools 8–10 above for email-code sign-in.

**Antigravity:** Merge into `mcp_config.json`.

```json
{
  "mcpServers": {
    "unseen": {
      "serverUrl": "https://unseendocs.in/mcp"
    }
  }
}
```

**Continue:** Merge into `~/.continue/config.yaml`.

```yaml
mcpServers:
  - name: unseen
    type: streamable-http
    url: https://unseendocs.in/mcp
```

- **n8n, Zapier and Make:** Use the same MCP URL above in your platform’s MCP client. Setup: [n8n](https://docs.n8n.io/integrations/builtin/credentials/mcp/) · [Zapier](https://help.zapier.com/hc/en-us/articles/38777069364109-Connect-remote-MCP-servers-to-Zapier-using-MCP-Client) · [Make](https://apps.make.com/c5ZhYquO55e90hoCJ0rzt). The [OpenAPI reference](https://unseendocs.in/api/openapi.json) is also available for REST integrations.
- **Agent Skill:** Read the [domain-hosted Skill](https://unseendocs.in/skills/unseen-workflow-compiler/SKILL.md) or the [public Skill repository](https://github.com/eyeinthesky6/unseen-workflow-compiler/tree/main/skills/unseen-workflow-compiler).