Skip to content

docs: improve agent discoverability (README, AGENTS.md, llms.txt) #2588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PeterHollens wants to merge 1 commit into
base: main
Choose a base branch
from
+501 −125
Open

docs: improve agent discoverability (README, AGENTS.md, llms.txt) #2588

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 71 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<a href="https://www.superdoc.dev" target="_blank">
<img alt="SuperDoc logo" src="https://storage.googleapis.com/public_statichosting/SuperDocHomepage/logo.webp" width="170px" height="auto" />
</a>
<BR />
<br />
<a href="https://www.superdoc.dev" target="_blank">
SuperDoc
</a>
Expand All @@ -17,9 +17,9 @@
</div>

<p align="center">
Copy link
Copy Markdown
Contributor

@caio-pizzol caio-pizzol Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we're keeping "Modern document editing and tooling" for now. AI agents are a big focus for us but the headline needs to cover all SuperDoc use cases, not just agent workflows.

<strong>The document engine for DOCX files.</strong><br>
Renders, edits, and automates .docx files in the browser, headless on the server, and within AI agent workflows.<br>
Self-hosted. Open source. Works with React, Vue, and vanilla JS.
<strong>The document engine for AI agents and teams that need real DOCX and PDF deliverables.</strong><br>
Renders, edits, and automates <code>.docx</code> files in the browser, headless on the server, and through stateless APIs.<br>
Tracked changes, comments, collaboration, signatures, and structured document workflows — built on real OOXML.
</p>

<div align="center">
Expand All @@ -28,7 +28,45 @@
</a>
Copy link
Copy Markdown
Contributor

@caio-pizzol caio-pizzol Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the "Best for / Not for" lists shift the README from developer docs toward product marketing. our brand leans toward "show, don't sell" — the current structure (quick start first, features second) fits better.

</div>

## Quick start
## Why SuperDoc

Use SuperDoc when your workflow needs a real document artifact — one that humans can review, redline, comment on, approve, sign, export, and send.

**Best for:**
- Legal redlines and contract review
- Due diligence memos and reports
- Proposal and response packs
- Template-driven document automation
- Human-in-the-loop agent workflows

**Not for:**
- Markdown publishing or blogs
- Note-taking apps
- Generic text generation
- "HTML now, export DOCX later" hacks

## Start Here

| I want to... | Start here |
|---|---|
| Embed a DOCX editor in my app | [Quickstart](https://docs.superdoc.dev/getting-started/quickstart) |
| Let an AI agent edit documents | [AI agents + MCP](https://docs.superdoc.dev/getting-started/ai-agents) |
| Run document workflows on the server | [Document Engine](https://docs.superdoc.dev/document-engine/overview) |
| Convert / annotate / sign / verify documents | [API reference](https://docs.superdoc.dev/api-reference/introduction) |
| Add real-time collaboration | [Collaboration guides](https://docs.superdoc.dev/modules/collaboration/overview) |

## Features

- **Real DOCX, not rich text** — Built on OOXML. Real pagination, section breaks, headers/footers, comments, and tracked changes. Not a contenteditable wrapper with export bolted on.
- **Built for agents** — MCP server, SDKs, CLI, and headless workflows. Agents read, edit, comment, and save real documents using structured operations.
- **Human review built in** — Tracked changes, comments, approvals, and collaboration in the same workflow agents use.
- **Stateless API** — Convert, annotate, sign, and verify documents without persistence. Process and return.
- **Real-time collaboration** — Yjs-based CRDT for multiplayer editing with shared state.
- **Self-hosted** — Runs entirely in the browser. Your documents never leave your servers.
- **Any framework** — React, Vue, Angular, Svelte, vanilla JS. One component, zero lock-in.
- **Dual licensed** — AGPLv3 for community use. [Commercial license](https://www.superdocportal.dev/get-in-touch) for proprietary deployments.

## Quick Start

```bash
npm install superdoc
Expand Down Expand Up @@ -80,30 +118,45 @@ Or use the CDN:

For all available options and events, see the [documentation](https://docs.superdoc.dev) or [SuperDoc.js](packages/superdoc/src/core/SuperDoc.js).

### Using an AI coding agent?
## For AI Agents

If your agent needs to produce a real Word or PDF artifact, start here.

Set up your project for AI agents and configure the MCP server:
### MCP server

```bash
npx @superdoc-dev/create # generates AGENTS.md for your framework
claude mcp add superdoc -- npx @superdoc-dev/mcp # connect agent to DOCX files
```

## Features
### Why agents use SuperDoc

- **Real DOCX, not rich text** — Built on OOXML. Real pagination, section breaks, headers/footers. Not a contenteditable wrapper with export bolted on.
- **Self-hosted** — Runs entirely in the browser. Your documents never leave your servers.
- **Any framework** — React, Vue, Angular, Svelte, vanilla JS. One component, zero lock-in.
- **Real-time collaboration** — Yjs-based CRDT. Multiplayer editing with comments, tracked changes, and automatic conflict resolution.
- **Agentic tooling** — Runs headless in Node.js. Bring your own LLM for document automation, redlining, and template workflows.
- **Dual licensed** — AGPLv3 for community use. [Commercial license](https://www.superdocportal.dev/get-in-touch) for proprietary deployments.
- Structured document operations — not brittle file mutation or string replacement
- Same document model across editor, SDK, and automation
- Tracked changes and comments as first-class outputs
- Reviewable artifacts humans already understand and trust

### Agent entry points

- [AI agents guide](https://docs.superdoc.dev/getting-started/ai-agents)
- [MCP server](https://docs.superdoc.dev/document-engine/ai-agents/mcp-server)
- [LLM tools](https://docs.superdoc.dev/document-engine/ai-agents/llm-tools)
- [AI Actions](https://docs.superdoc.dev/ai/ai-actions/overview)
- `llms.txt` / `llms-full.txt`

## Use Cases

- **AI redlining** — Turn instructions into tracked changes and comments on real DOCX files
- **Diligence memos** — Gather facts, draft a memo, and deliver a review-ready Word document
- **Proposal automation** — Assemble response packs, compliance tables, and export-ready PDFs
- **Contract workflows** — Draft, review, collaborate, sign, and verify end to end

## Examples

Starter projects to get you running quickly:
Starter projects and workflows:

| Example | |
|---------|--|
|---|---|
| [React](examples/getting-started/react) | [Vue](examples/getting-started/vue) |
| [Angular](examples/getting-started/angular) | [Next.js](examples/getting-started/nextjs) |
| [Vanilla JS](examples/getting-started/vanilla) | [CDN](examples/getting-started/cdn) |
Expand All @@ -115,11 +168,11 @@ Starter projects to get you running quickly:

## Documentation

[docs.superdoc.dev](https://docs.superdoc.dev) — installation, integration guides, collaboration setup, API reference, and more.
[docs.superdoc.dev](https://docs.superdoc.dev) — installation, framework guides, collaboration, AI workflows, document engine, API reference, and more.

## Roadmap

See the [SuperDoc roadmap](https://github.com/superdoc-dev/superdoc/issues/1982) for what's coming next. DOCX import/export fidelity is always a top priority.
See the [SuperDoc roadmap](https://github.com/superdoc-dev/superdoc/issues/1982) for what's coming next. DOCX fidelity and production-grade document workflows remain top priorities.

## Contributing

Expand Down
Loading
Loading