# SuperDocs Integration Starter Prompt — Universal Template

Paste this prompt into your coding agent (Claude Code, Cursor, Windsurf, Codex, Cline, or any other) to integrate SuperDocs into your product. This template is designed to work for any integration shape — a brand-new app, an existing app with an editor, an existing AI agent that needs document-editing capability, a server-side batch worker, an MCP client, or anything else.

**Target fill time: under 5 minutes.** Almost everything below is optional. The agent reasons from the SuperDocs API docs + your existing context (`CLAUDE.md`, `package.json`, your codebase) and adapts the integration to your product. It will tell you what it inferred before it starts writing code, and you'll have one chance to correct it.

This template is published at https://docs.superdocs.app/guides/integration-starter-prompt. The filled-in ProseMirror + Next.js reference implementation lives at https://github.com/superdocsapp/prosemirror-superdocs-demo.

---

## Part 0 (recommended) — How do you want SuperDocs in your product?

In 1-3 sentences, describe what you want SuperDocs to do in your product. This is the strongest single signal the agent uses to determine which integration shape applies.

**If you fill this in:** the agent goes straight to the investigation framework with a clear target shape.

**If you leave it blank:** the agent reads your `CLAUDE.md` (or whichever context file is in your project root), infers the most likely integration shape from your codebase, and **proposes a plain-English integration plan for you to approve before writing any code.** You can correct or redirect the proposal — the agent will not start writing code until you confirm the shape.

Examples (don't copy verbatim — describe YOUR situation):

- "Brand-new app from scratch with a rich-text editor on the left and a chat panel on the right."
- "Existing Next.js app with a TipTap editor; add SuperDocs as the AI editing engine, surfaced through the editor's existing slash-command menu."
- "Existing AI agent (built with OpenAI function-calling / LangChain / LlamaIndex / Anthropic tool_use) that handles customer queries — add SuperDocs as a tool the agent can call when it needs to edit a document."
- "Backend service that processes contracts overnight via a queue worker — no UI, no human approval, fully automated. Auto-approve all SuperDocs edits."
- "Want my Claude Desktop / Cursor / VS Code IDE to be able to edit my docs via SuperDocs MCP."
- (Anything else — describe the user flow in your product and the agent will figure out where SuperDocs slots in.)

```
[describe your situation here in 1-3 sentences — or leave blank to let the agent propose a plan from your CLAUDE.md / codebase]
```

---

## Part 0A — Existing context (recommended for most teams)

Most teams already maintain a file that describes their product, stack, and conventions in a form a coding agent reads fluently — typically `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, or similar in the project root.

**If you have one of these files in your project root, you do not need to do anything in this section** — the agent will discover and read it automatically as the first step of the protocol below. Skip to running the prompt.

If your context lives somewhere other than the project root (a Notion page, a Confluence doc, a different filename, an internal brief), use one of the three options below to point the agent at it.

**Pick one of the three options. You do not need to do all three.**

### Option 1 — Paste your existing agent context

If your team has a `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, internal developer brief, or equivalent, paste its contents between the markers below. The coding agent will infer the Part 0B declarations from this context.

```
<!-- paste your CLAUDE.md / AGENTS.md / .cursorrules / internal brief here -->
```

### Option 2 — Link to existing internal docs

If your context lives in Notion, Confluence, a GitHub README, or a public docs site, list the URLs below. The coding agent will fetch and read them before proceeding.

- <!-- URL 1 -->
- <!-- URL 2 -->

### Option 3 — Paste your package manifest + one representative file

If you don't have agent context yet but have an existing codebase, paste your package manifest (`package.json`, `requirements.txt`, `Gemfile`, `go.mod`, `pyproject.toml`, etc.) and the path to one file that handles documents today — the current editor component, the current upload endpoint, whatever is closest to where SuperDocs will plug in.

```
<!-- package manifest here -->
```

Representative file path(s):

- <!-- path to one file the agent should read first -->

### If none apply

Skip Part 0A entirely. The agent will still auto-discover any context file in your project root and infer remaining values from your codebase once it starts reading files.

---

## Part 0B — Optional declarations

Fill in whatever you already know. Leave the rest blank — the coding agent will read your codebase and infer each missing value, then echo its inferences back before writing code. **Do not fill these in defensively.** Agents that have read your actual `package.json`, editor component, and framework files produce better picks than blanket defaults.

### Descriptive slots

- **EXISTING_APP_CONTEXT:** _(describe the codebase — only relevant if this is not a greenfield build. Leave blank to let the agent read the repo itself.)_
- **DOC_FLOW_DESCRIPTION:** _(how documents currently enter, live in, and leave the product. Leave blank to let the agent infer from the codebase.)_
- **SAMPLE_DOCUMENT:** _(starting HTML for the demo's first edit. Leave blank to let the agent generate or pick one from your existing data.)_
- **EXISTING_EDITOR_FILE_PATH:** _(if you have a rich-text editor, the path to its component file. Leave blank — the agent will find it via file search.)_

### Scenario axes — all optional

Fill in a value if you have a firm preference. Leave blank to let the agent choose based on your codebase — it will echo back its pick before starting.

- **APP_MATURITY:** `greenfield` · `existing-no-editor` · `existing-with-editor` · `existing-with-ai-agent` _(leave blank to detect from the repo.)_
- **EDITOR_FRAMEWORK:** `prosemirror` · `tiptap` · `slate` · `lexical` · `quill` · `ckeditor` · `contenteditable` · `none` · `other` _(leave blank to detect from `package.json`.)_
- **AUTH_STATE:** `none-demo-only` · `firebase` · `auth0` · `clerk` · `custom-sessions` · `enterprise-sso` _(leave blank to detect.)_
- **BACKEND_STATE:** `next-api-routes` · `express` · `fastapi` · `rails` · `django` · `go` · `dotnet` · `serverless` · `other` _(leave blank to detect from project layout.)_
- **LANGUAGE:** `typescript` · `javascript` · `python` · `go` · `ruby` · `java` · `csharp` · `php` _(leave blank to detect from file extensions.)_
- **FRONTEND_FRAMEWORK:** `nextjs` · `remix` · `vite-react` · `sveltekit` · `vue` · `plain-html` · `rails-view` · `django-template` · `htmx` · `desktop` · `none` (server-only) _(leave blank to detect.)_
- **DEPLOYMENT_TARGET:** `localhost-demo` · `browser-saas` · `server-only-no-ui` · `desktop-app` · `mcp-only` · `agent-tool` _(leave blank — Part 0 usually answers this.)_
- **APPROVAL_MODE:** `human-via-ui` · `ai-decides` · `auto-approve-all` · `human-out-of-band` (Slack, email) _(leave blank — Part 0 usually answers this.)_
- **API_KEY_STORAGE_PREFERENCE:** `env-var` · `secrets-manager` · `vault` · `existing-config-file` · `other` _(leave blank to detect from your existing secret-handling patterns.)_

---

## Agent protocol — read, infer, echo back, ask, wait

Before executing **any** part of the integration, the coding agent must:

1. **READ CONTEXT.** Before doing anything else:
   a. Search the project root for any context files the integrator may have already maintained. Look for, in this order: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, `.aiderrules`, `GEMINI.md`, `COPILOT.md`, `INSTRUCTIONS.md`, or any file matching the pattern `*RULES*.md` / `*AGENT*.md` / `*INSTRUCTIONS*.md` in the project root. If any of these exist, read all of them — these files describe the integrator's product, stack, and conventions and are higher-priority context than anything else. Do NOT assume your coding-agent harness auto-loaded them; read them explicitly via your file-read tool so you know what's in them.
   b. Read every file and URL provided in Part 0A (paste-in context, links to internal docs, package manifests).
   c. Read the integrator's existing codebase — at minimum, the package manifest (`package.json`, `requirements.txt`, `Gemfile`, `go.mod`, `pyproject.toml`, etc.), the main framework config files, any editor component or AI-agent file if declared or discoverable, and the `README` if present.
   d. **Fetch the SuperDocs API reference fresh from `https://docs.superdocs.app/llms-full.txt`** — even if a stale local copy exists. Run `curl -sS https://docs.superdocs.app/llms-full.txt -o llms-full.txt` to grab the current version. The live URL is always authoritative; the local copy may be days or weeks old.
2. **INFER.** For every Part 0B slot the integrator left blank, infer the value from context. If a slot cannot be inferred with reasonable confidence, mark it as `UNSET`.
3. **RUN THE INVESTIGATION FRAMEWORK** in Part 4 §C below. Answer all five questions about the integrator's product. If you can't answer a question from available context, mark it `UNSET — asking you`.
4. **ECHO BACK.** Present every Part 0B value AND every Part 4 §C answer with a source tag:
   - `[provided]` — the integrator explicitly set this in Part 0 / Part 0B / Part 0A.
   - `[inferred from <file or signal>]` — name the source.
   - `[UNSET — asking you]` — genuinely ambiguous.
5. **ASK.** For each `UNSET` slot, ask the integrator specifically, offering 2–3 suggested options.
6. **PROPOSE A PLAN (only if Part 0 was left blank).** If the integrator did not describe their integration goal in Part 0, synthesize a 1-paragraph plain-English integration proposal from your §C answers and Part 0B inferences. Frame it as: *"Here's what I understood from your codebase. I propose to build [X], surfaced in [Y], with [Z] approval mechanism. Confirm or correct this before I start writing code."* Do NOT proceed until the integrator confirms the proposed shape.
7. **WAIT.** Do not start writing code until the integrator has confirmed the inferred values, answered any `UNSET` questions, and (if applicable) approved the proposed integration plan.

This prevents the agent from confidently integrating into the wrong shape because it misread pasted context or guessed at an ambiguous axis.

---

## Last-resort fallback (only when no signal at all)

If the agent cannot infer anything from context AND the integrator has left Part 0 blank AND cannot answer follow-up questions, the agent may proceed with the following blanket fallback — **but must announce it clearly before starting:**

> *"I had no context to work with, so I'm defaulting to the fastest-to-ship demo stack below. Tell me to stop if this isn't what you want."*

- **Integration shape:** greenfield UI build (editor + chat panel)
- **LANGUAGE:** `typescript`
- **FRONTEND_FRAMEWORK:** `nextjs`
- **EDITOR_FRAMEWORK:** `tiptap` (lower chunk-id-schema friction than raw ProseMirror for a blind start)
- **BACKEND_STATE:** `next-api-routes`
- **AUTH_STATE:** `none-demo-only`
- **APPROVAL_MODE:** `human-via-ui`
- **API_KEY_STORAGE_PREFERENCE:** `env-var`
- **DEPLOYMENT_TARGET:** `localhost-demo`

This fallback is for the genuinely-no-signal case only. Inference from any real context — package manifest, existing editor or AI-agent files, repo layout, customer's Part 0 description — always beats this blanket stack.

---

## Dry-run checklist (verify before declaring the integration done)

Whatever shape your integration takes, verify these five universal checks:

1. **Document HTML round-trip preserves `data-chunk-id` attributes.** Send a real document HTML to SuperDocs, receive the response, send the response back unchanged on the next request, verify the `chunk_id` references in `proposed_change_batch` events match elements that exist in your document.
2. **API key is server-side only.** No browser network request should contain the `sk_` value. Verify in DevTools or your backend logs.
3. **At least one full round-trip succeeds end-to-end.** A user (or your AI, or your batch worker) sends a message; SuperDocs returns proposed changes; those changes are surfaced (UI / agent / log) per your declared `APPROVAL_MODE`; approved changes apply to the document.
4. **Failure modes are handled.** If the SuperDocs API returns 4xx/5xx, your code surfaces a useful error. If the SSE stream drops, your code reconnects or surfaces an error.
5. **Your integration matches your product's existing idioms.** Don't introduce a new state library, new component framework, or new HTTP client just for SuperDocs. Match what your codebase already uses.

---

## Part 1 — Mandatory context

Read these before writing code:

1. **The full SuperDocs API reference at `https://docs.superdocs.app/llms-full.txt`.** Fetch the latest version yourself — do not assume a local copy is current:
   ```bash
   curl -sS https://docs.superdocs.app/llms-full.txt -o llms-full.txt
   ```
   Run this even if a stale `llms-full.txt` already exists in the project folder; the API surface evolves and the live URL is always authoritative. Refer to this file whenever an API question comes up.
2. This prompt, Parts 2–8.
3. Your own codebase — read enough of `EXISTING_APP_CONTEXT` paths to understand where documents live, where your authenticated backend routes live, and how your frontend (or your AI agent) consumes data.

Do not search the internet for integration patterns beyond these sources. Everything you need is in `llms-full.txt`, in this template, or in the linked docs guides.

---

## Part 2 — Hard constraints

### Must always be true of any SuperDocs integration

- The integration produces a working "send document → receive proposed changes → apply approved changes" loop appropriate to the product's existing patterns.
- The SuperDocs `sk_` API key is never exposed to a browser, mobile app, or any client-side surface.
- The document HTML (with `data-chunk-id` attributes) round-trips cleanly between wherever the document lives and SuperDocs.
- The approval mechanism (human-via-UI, AI-decides, auto-approve, human-out-of-band) matches what `APPROVAL_MODE` declares (or what Part 0 implies).

### Stack — match the customer's existing system

Do NOT impose Next.js, ProseMirror, Tailwind, or any other specific stack on a project that isn't already using it. If the customer's codebase is Rails + Slate + plain CSS, the integration is Rails + Slate + plain CSS. The reference implementation in the GitHub repo uses Next.js + ProseMirror + Tailwind because that's what the demo video builds — your job is to adapt the patterns to the customer's actual stack, not to scaffold a duplicate stack alongside theirs.

### Out of scope for a first integration

- Attachments, image uploads, and templates. All exist in the API; they're separate integrations.
- Multi-document UI, session list, user impersonation. Not part of the API integration.

### Content safety — what to never include in your code, comments, or public-facing artefacts

- Specific AI model names (the SuperDocs API includes the model; your users do not need to know which one).
- Third-party orchestration framework names that SuperDocs might use internally.
- Cloud provider names beyond "hosted" or "server-side."
- Database technology assumptions about SuperDocs' own backend.
- Cost-per-operation numbers or internal SuperDocs pricing.

Say "SuperDocs' AI" or "the AI" when you need to refer to the model.

---

## Part 3 — Standing rules during the build

1. **Strong types.** Whatever your language, use the strictest practical type mode. No `any`, no `interface{}`, no untyped dicts at boundaries.
2. **No decorative error handling.** If an HTTP call fails, let it surface to a toast / log / return value — don't paper it over with silent catches.
3. **Comments only where the *why* is non-obvious.** Do not narrate what the code does.
4. **Commit after every phase** (locally; don't push until the integration works end-to-end). If something breaks in Phase N+1, `git reset` is one keystroke away.
5. **Read `llms-full.txt` whenever an API question comes up.** It is always the answer faster than guessing.
6. **Match the customer's idioms.** If their codebase uses Express middleware patterns, write Express middleware. If it uses class-based services, write a class-based service. Don't introduce new patterns.

---

## Part 4 — Universal Integration Framework

This Part replaces the per-shape phase trees you might expect from a typical integration guide. SuperDocs deliberately reasons from principles rather than enumerating every possible customer architecture, because customer systems are too varied for a fixed set of templates. The framework below works for every shape — UI build, AI-agent tool, server-side worker, MCP client, embedded-in-existing-editor, custom — by giving the agent everything it needs to reason from your specific product.

### §A — Integration principles

What SuperDocs requires from any integration, regardless of shape:

1. **Documents are HTML in / HTML out.** SuperDocs accepts an HTML document and returns an HTML document. There is no proprietary format — you send and receive standard HTML strings.
2. **`data-chunk-id` attributes on block-level elements must round-trip cleanly.** SuperDocs returns HTML with `data-chunk-id="<uuid>"` attributes on paragraphs, headings, lists, blockquotes, code blocks, and other block-level elements. Whatever holds your document (rich-text editor, database row, in-memory string, file storage) must preserve these attributes when the document goes back to SuperDocs on the next request. Failure mode is silent: surgical editing intermittently fails on chunks whose attribute was stripped.
3. **The integration loop is always the same shape.** Send document HTML + a message → receive proposed changes (one or many) → decide which to apply (human, AI, or auto-approve) → apply approved changes → persist the resulting HTML back to wherever the document lives.
4. **Approval can take many shapes.** A human reviewing a UI diff card. A human notified out-of-band (Slack, email) who replies with approval. Your AI agent making the decision based on its own reasoning. Auto-approve-all for batch processing where no review is wanted.
5. **Streaming (SSE) is one option, not the only option.** For interactive user-facing flows, SSE gives the best UX (progress events, mid-flight diffs). For server-side batch processing or AI-agent-tool integration, the synchronous `/v1/chat` endpoint or polling on `/v1/jobs/{id}` are simpler and equally valid.
6. **Your existing system's idioms are the right idioms.** SuperDocs is one piece of plumbing among many in your product. The integration code should look like the rest of your codebase — same HTTP client, same error handling, same logging conventions, same component patterns.

### §B — Canonical minimal example (the loop in 15 lines)

Whatever shape your integration ends up taking, this is the conceptual core. Every richer integration is a wrapper around this loop:

```bash
# Set your key once
export SUPERDOCS_API_KEY="sk_YOUR_KEY"

# One round-trip: send a document + a message, get the edited document back.
curl -sS -X POST https://api.superdocs.app/v1/chat \
  -H "Authorization: Bearer $SUPERDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Make the introduction one sentence shorter.",
    "session_id": "demo-1",
    "document_html": "<h1>Welcome</h1><p>Hello from our application. We are glad you are here.</p>",
    "approval_mode": "approve_all"
  }' \
| jq -r '.document_changes.updated_html'
```

Output: the updated HTML, ready to render or persist back to wherever your document lives.

That's the whole loop. Every integration shape — editor + chat, AI-agent tool, server-side worker, MCP client — is a richer version of this same call:

- An editor + chat UI wraps the call in a frontend that sends the editor's HTML, streams progress via SSE, and applies the result back to the editor via a `setHtml()` bridge.
- An AI agent wraps the call in a tool function that the agent invokes when it decides a document edit is needed.
- A server-side worker iterates a queue, calling this loop synchronously per document, persisting the result to storage.
- An MCP client connects to `https://api.superdocs.app/mcp/` and lets a meta-agent (Claude Desktop, Cursor) trigger the same call.

The SSE variant adds streaming progress and human-in-the-loop review. The polling variant adds the ability to fire-and-forget for long jobs. But the principle is unchanged: HTML in, HTML out, with optional approval in the middle.

### §C — Investigation framework

Before writing any integration code, you (the agent) MUST answer these five questions about the integrator's product. Output a short decision document (5-10 lines) and present it for the integrator's confirmation before proceeding to §D.

1. **Where does the document HTML come from?** (rich-text editor in a browser / file storage like S3 or local disk / database row / API endpoint / generated by another AI step / pasted by a user / streamed in from another system)
2. **Who decides whether a proposed change is applied?** (a human via UI / your AI agent making the decision based on its own reasoning / auto-approve all changes / a human notified out-of-band, e.g. via Slack or email)
3. **Where does the approved HTML go?** (back into the same editor / persisted to storage / pushed to another system / returned via API to a caller / written to a file)
4. **What's your product's idiom for handling streaming or async events?** (web SSE / WebSocket / polling / queue worker / synchronous request-response / message bus)
5. **Does any pattern in your existing system look similar to what SuperDocs is being added to do?** (existing rich-text edit flow, existing AI suggestion flow, existing document workflow, existing content moderation, existing review queue, etc.) Match the new integration to the existing idiom — don't invent a new pattern.

If a question can't be answered from the available context, mark it `UNSET — asking you` and ASK the integrator before proceeding. Do not invent answers.

### §D — Universal 5-phase tree

These five phases apply regardless of integration shape. Each phase has a one-paragraph description of WHAT to build (not how) and a pointer to the relevant docs page for the HOW.

#### Phase 1 — Investigate and confirm

Run the §C investigation framework. Output a short decision document covering all five questions plus the Part 0B declarations. Present it to the integrator for confirmation. Do not proceed to Phase 2 until confirmed.

#### Phase 2 — Set up the API client

Create a server-side wrapper around the SuperDocs API in a module appropriate to the customer's stack — a Next.js API route, an Express middleware, a FastAPI endpoint, a Rails controller, a Go handler, a .NET minimal-API endpoint, etc. The `sk_` API key never reaches a browser, mobile app, or any client-side surface; it lives in the backend's environment / secret store.

→ For the Next.js / Express / FastAPI / Rails / Django / Go / .NET API-key proxy patterns: **https://docs.superdocs.app/guides/streaming** (the same guide also covers SSE auth setup with the `api_key` query param required by `EventSource`).

→ For server-side-only integrations (no browser, no proxy required): **https://docs.superdocs.app/guides/server-integration**.

#### Phase 3 — Implement the document round-trip

Build the "send HTML → receive proposed changes" loop in your customer's idiom. The shape varies:

- If the customer's product has a rich-text editor: wire the editor to `getHtml()` / `setHtml()` bridges, send via the API client from Phase 2, render proposed changes via the approval mechanism in Phase 4.
- If the customer's product has an AI agent: register SuperDocs as a tool the agent can invoke, with the tool function calling the API client from Phase 2 and returning structured proposed-change data the agent can reason about.
- If the customer's product is a server-side worker: pull documents from your queue / storage, call the API client from Phase 2 with `approval_mode: "approve_all"`, persist the returned HTML back to storage.
- If the customer's product is an MCP client: configure the client to connect to `https://api.superdocs.app/mcp/`. There is no code to write — it's a configuration step.

→ For editor integrations (preserving `data-chunk-id` round-trip in ProseMirror, TipTap, Slate, Lexical, Quill, CKEditor, or contenteditable): **https://docs.superdocs.app/guides/editor-integration**.

→ For AI agent tool integrations (registering SuperDocs as a tool in OpenAI function-calling, Anthropic `tool_use`, LangChain, LlamaIndex, or any other tool-using framework): **https://docs.superdocs.app/guides/agent-tool-integration**.

→ For server-side / batch / queue-worker integrations (sync API, polling, `approval_mode: "approve_all"`): **https://docs.superdocs.app/guides/server-integration**.

→ For MCP clients (Claude Desktop, Cursor, VS Code, Windsurf, Claude Code): **https://docs.superdocs.app/mcp/setup**.

#### Phase 4 — Implement the approval mechanism

Build the appropriate approve/deny flow based on §C question 2:

- **`human-via-ui`** — render proposed changes as inline diff overlays in the editor, side-by-side cards in a chat panel, modals, notification toasts, or whatever pattern your UI already uses. On approve, POST to `/v1/chat/{session_id}/approve`.
- **`ai-decides`** — your AI agent receives the proposed change as structured data (chunk_id, old_html, new_html, ai_explanation) and decides whether to approve based on its own reasoning. Same approve POST, but the decision is made by the agent.
- **`auto-approve-all`** — pass `approval_mode: "approve_all"` in the initial request. SuperDocs applies all changes without pausing for review. No second API call needed.
- **`human-out-of-band`** — your service sends a notification (Slack, email, SMS) with the proposed change, waits for the human's response (button click, reply, etc.), then POSTs to `/v1/chat/{session_id}/approve`.

→ For human UI approval patterns (inline diff overlay, side-by-side cards, modals, etc.): **https://docs.superdocs.app/guides/human-in-the-loop**.

→ For AI-driven approval inside an agent's reasoning loop: **https://docs.superdocs.app/guides/agent-tool-integration**.

#### Phase 5 — Test end-to-end

Run a real document through the full loop. Verify the dry-run checklist above. Verify the customer's actual product (whatever it looks like) shows the expected outcome — an editor that updates in place, an AI agent that completes its reasoning with the document edited, a queue worker that produces edited documents in storage, etc.

### §E — Per-pattern cross-references

This table maps common implementation choices to the right docs page. Use it to find the snippet that matches your customer's product:

| If your product has... | Look here for the implementation pattern |
|---|---|
| A rich-text editor (ProseMirror, TipTap, Slate, Lexical, Quill, CKEditor, contenteditable, custom) | [Editor Integration](https://docs.superdocs.app/guides/editor-integration) |
| An existing AI agent (OpenAI function-calling, Anthropic `tool_use`, LangChain, LlamaIndex, generic JSON-schema tool) | [Agent Tool Integration](https://docs.superdocs.app/guides/agent-tool-integration) |
| A backend service / queue worker / batch job (Node, Python, Go, Ruby, .NET, etc.) with no UI | [Server Integration](https://docs.superdocs.app/guides/server-integration) |
| HITL approval rendered in your UI | [Human-in-the-Loop](https://docs.superdocs.app/guides/human-in-the-loop) |
| Real-time streaming (SSE) for progress events | [SSE Streaming](https://docs.superdocs.app/guides/streaming) |
| Long-running async jobs with polling | [Async Jobs](https://docs.superdocs.app/guides/async-jobs) |
| MCP client integration (Claude Desktop, Cursor, VS Code, Windsurf) | [MCP Setup](https://docs.superdocs.app/mcp/setup) |
| Working code in a specific language | [JavaScript](https://docs.superdocs.app/examples/javascript), [Python](https://docs.superdocs.app/examples/python), [curl](https://docs.superdocs.app/examples/curl) |

### §F — Stuck?

If your integration shape isn't listed in §E and the principles in §A don't obviously map to your product, email `hello@superdocs.app` or book a 15-minute integration call at `https://cal.com/superdocs`. We'll talk through the pattern and add a snippet to the docs for the next person.

---

## Part 5 — API contract summary

All requests go through your API client (Phase 2). Paths are relative to `https://api.superdocs.app/`.

- `POST v1/chat` — sync: body `{ message, session_id, document_html, approval_mode?: "approve_all" | "ask_every_time", document_id? }` → returns the full result inline. Best for batch / server-side / agent-tool integrations that don't need streaming. `document_id` targets a specific open document in multi-document sessions (omit = focused document).
- `POST v1/chat/async` — async: body same as above → returns `{ job_id }`. Use with the SSE stream or polling endpoint.
- `GET v1/chat/{session_id}/stream?job_id=...&api_key=...&last_sequence=...` — SSE stream of nine event types (`intermediate`, `proposed_change_batch`, `document_sync`, `continue_prompt`, `documents_changed`, `model_fallback`, `final`, `usage`, `error`). `proposed_change_batch` is the event that carries proposed changes for human review (its `changes[]` array holds the whole batch — single-change turns arrive as a one-element array). Browser-side requires the `api_key` query param because `EventSource` can't set custom headers; on reconnect pass `last_sequence` to replay only newer events.
- `GET v1/jobs/{job_id}` — poll for async job status. Use as an alternative to SSE for non-browser consumers.
- `POST v1/chat/{session_id}/approve` — body: `{ job_id, approved, changes?: [{ change_id, approved, feedback? }] }`. Resumes the AI on the already-open SSE stream.
- `GET v1/sessions/{session_id}/documents` — list the session's open documents (multi-document sessions): ids, chunk counts, focused flag, HTML. `POST .../documents/{document_id}/focus` switches focus; `DELETE .../documents/{document_id}?next_focus=...` closes one.
- `POST v1/sessions/{session_id}/revert` — body: `{ turn_index }` → returns `{ compose_text, reverted_to_turn, document_state, editor_action, archived_turn_count }`. Rewinds chat + document to the state before the user message at `turn_index`. Returns `409` if a chat job is in flight on the session, `422` if the target message predates the revert feature.
- `POST v1/documents/export` — body: `{ html?, session_id?, upload_id?, format: "docx" | "pdf" | "html" | "markdown" | "txt", options?, filename? }` → binary file (`docx` default). Non-fatal issues arrive in the `X-Export-Warnings` response header.

SSE event `data:` shapes (all JSON):

```
document_sync         { type, content }                  // content: full HTML
intermediate          { type, content, sequence, timestamp }
proposed_change_batch { type, content, sequence }        // content: JSON-stringified batch (changes[])
final                 { content, result }                // result.response, result.document_changes.updated_html
usage                 { monthly_used, monthly_limit, monthly_remaining, was_billable, subscription_tier }
error                 { error }
```

`proposed_change_batch` is the event that carries proposed changes for human review. The whole turn arrives as **one** event whose `changes[]` array holds every proposed change — even a single-change turn arrives as a one-element array. (You may also register a `proposed_change` listener defensively for forward-compatibility, but it never fires today — `proposed_change_batch` is what's emitted, so build your approval loop on it.)

`proposed_change_batch.content` is a JSON-stringified string — you must `JSON.parse` it twice to access the batch. See the warning callout in the [SSE Streaming guide](https://docs.superdocs.app/guides/streaming).

Parsed `proposed_change_batch.content` shape:
```
{ batch_id, batch_total,
  changes: [
    { change_id, operation: "edit" | "create" | "delete",
      chunk_id, old_html, new_html,
      ai_explanation, document_id, insert_after_chunk_id },
    ...
  ] }
```

Iterate `changes[]` to render each proposed change; call `/approve` with the `change_id` of each.

---

## Part 6 — Failure modes and their fixes

| Symptom | Likely cause | Fix |
|---|---|---|
| `Missing SUPERDOCS_API_KEY` | env file not read | Restart your server; env vars are read on boot. |
| 401 from any endpoint | key wrong or includes `Bearer ` literal | Value is just `sk_...` with no quotes, no "Bearer" prefix. |
| SSE connection opens then closes | proxy transforms or buffers headers | Pipe upstream body unchanged; set `Cache-Control: no-cache, no-transform`. Disable buffering at any reverse proxy (nginx, Caddy, CloudFront). |
| `proposed_change_batch` fires, approve POST returns 404 | wrong session_id in the URL | Path must include the session ID exactly as sent in the original `/v1/chat/async` request. |
| Revert returns 409 | A chat job is in flight on the session | Wait for the SSE `final` event (or poll `/v1/jobs/{job_id}` until status is `completed`/`failed`) before retrying revert. Optionally cancel the job via `POST /v1/jobs/{job_id}/cancel` first. |
| Revert returns 422 | The target user message predates the revert feature | Per-message revert only works on chats started after the feature shipped. Older sessions stay readable but their messages don't carry the rewind marker. Start a new session for full revert support. |
| Document loses `data-chunk-id` after first edit | editor schema/config missing a node type | Add the missing node to your chunk-id-preservation config (see [Editor Integration](https://docs.superdocs.app/guides/editor-integration)). |
| Diff card has empty `old_html` | operation is `create`, not `edit` | Correct — creates have no `old_html`. Render them as "new section" cards. |
| `proposed_change_batch.content` fields all undefined | missed the JSON double-parse | `JSON.parse(JSON.parse(event.data).content)` to access the batch, then iterate its `changes[]`. |
| Silent round-trip loss of attributes | HTML sanitizer strips unknown attributes | Add `data-chunk-id` to your sanitizer's allowlist. |
| AI agent's tool call fails to parse the response | agent expects JSON but SuperDocs returned HTML in the `updated_html` field | The HTML is the value; pass it through to wherever your document lives. The agent should treat it as opaque content, not parse it. |

---

## Part 7 — Self-review checklist

Verify all applicable items before declaring the integration done. Skip items gated on scenarios you didn't enable.

- [ ] You answered all five §C investigation questions and got integrator confirmation.
- [ ] A user message (or your agent's tool call, or your worker's queue item) reaches SuperDocs with the current document HTML attached.
- [ ] At least one full round-trip succeeds end-to-end and produces a visible result in the customer's actual product.
- [ ] The SuperDocs `sk_` key never appears in any browser network request, mobile app log, or other client-side surface.
- [ ] The `data-chunk-id` attribute survives the round-trip on every block node type your product uses (verify with a real document, not a synthetic one).
- [ ] If using SSE streaming or `approval_mode="ask_every_time"` (or any operation that may take >10 seconds), `intermediate` progress events are rendered to the user as in-flight chat bubbles or a progress indicator. The user sees text updates arriving every few seconds — never a silent screen for 30+ seconds. Long operations on large documents can take minutes; a frozen UI looks identical to a crashed one. See [Streaming → Rendering intermediate events in your UI](/guides/streaming#rendering-intermediate-events-in-your-ui).
- [ ] Your client validates that `document_html` is non-empty before sending. Editor refs can be transiently `null` during framework remounts (React Strict Mode, HMR, Fast Refresh) and silently return empty strings — cache the last successful `document_html` (from the previous `final.updated_html` or your editor's confirmed state) and fall back to it before sending.
- [ ] The approval mechanism matches what `APPROVAL_MODE` declared (human-via-UI / AI-decides / auto-approve / human-out-of-band).
- [ ] A second message in the same session continues the conversation (the AI refers back to the prior edit).
- [ ] Failure paths are handled — bad API responses surface useful errors; dropped streams reconnect or surface errors.
- [ ] The integration matches your product's existing idioms (HTTP client, error handling, component patterns) — no foreign-looking code.

---

## Part 8 — Content safety (last reminder)

Nothing in your code, comments, commit messages, or public artefacts mentions specific AI model names, orchestration framework names, internal SuperDocs tech names, cloud providers, or cost-per-operation figures. Say "SuperDocs' AI" or "the AI."

---

## You are now starting

Confirm with the integrator that the Part 0 description, Part 0B inferences, and §C investigation answers are correct, then execute Phases 1–5 in order. Read `llms-full.txt` and the linked docs guides whenever an API question or implementation question comes up. Commit locally after every phase. Do not push until the end-to-end integration works.

Good luck.