twofold

One document, two views.

Your agent wrote 15 pages. Humans see what matters. Agents see everything.

The Problem

AI generates cathedrals of content. A quarterly report becomes 15 pages of structured data, citations, methodology notes. Humans can't process that. But the next agent in your pipeline needs all of it.

There is no format that serves both audiences from one source. You either dumb it down for humans or bury them in detail meant for machines. Twofold is one markdown file that renders two views: a human gets the executive summary, an agent gets the full corpus. Same URL. Same document. Two layers, authored intentionally.

How It Works

Write markdown. Mark the agent-only sections with HTML comments:

---
title: Q1 Revenue Report
slug: q1-revenue
theme: clean
expiry: 30d
---

# Q1 Revenue Report

Revenue grew 23% YoY driven by enterprise expansion.
Key risk: churn in mid-market segment accelerating.

Recommendation: shift acquisition spend to retention for Q2.

<!-- @agent -->

## Detailed Breakdown

| Segment | ARR | Growth | Churn |
|---------|-----|--------|-------|
| Enterprise | $4.2M | +31% | 2.1% |
| Mid-market | $1.8M | +12% | 8.7% |
| SMB | $0.6M | -3% | 14.2% |

## Methodology

Growth figures are trailing-twelve-month calculations normalized against...
[12 more pages of tables, analysis, source citations]

<!-- @end -->

Human visits share.example.com/q1-revenue -- sees a styled page with the summary. Three paragraphs. Done.

Agent hits share.example.com/api/v1/documents/q1-revenue -- gets everything. All 15 pages. Raw markdown with frontmatter intact.

The markers are HTML comments. They're invisible in any standard markdown renderer. Any LLM can emit them. Without twofold, the document degrades gracefully to normal markdown with some comments in it.

Quick Start

# Build from source
git clone https://github.com/gabaum10/twofold.git
cd twofold
cargo build --release

# Run it
export TWOFOLD_TOKEN="your-secret-token"
./target/release/twofold serve

# Publish a document
curl -X POST http://localhost:3000/api/v1/documents \
  -H "Authorization: Bearer $TWOFOLD_TOKEN" \
  -H "Content-Type: text/markdown" \
  --data-binary @report.md

# Response:
# {"slug":"q1-revenue","url":"http://localhost:3000/q1-revenue"}

Or pipe from stdin:

cat report.md | ./target/release/twofold publish --server http://localhost:3000 --token $TWOFOLD_TOKEN

Features

• Frontmatter -- title, slug, theme, expiry, password, description (YAML in --- fences)
• Custom slugs -- choose your URL or let nanoid generate one
• Expiry -- documents self-destruct (30m, 24h, 7d, 2w) with background reaper
• Password protection -- per-document, argon2-hashed, cookie-based session
• Themes -- clean (default), dark, paper, minimal, hearth
• Syntax highlighting -- syntect-powered, theme-aware (light/dark palettes)
• Full CRUD -- create, read, update, delete via REST
• MCP server -- agents publish and retrieve natively via JSON-RPC over stdio
• Webhooks -- fire on create/update/delete, HMAC-signed
• Agent discovery -- <link rel="alternate" type="text/markdown"> in every HTML page
• OpenAPI spec -- served live at /api/v1/openapi.yaml and /api/v1/openapi.json
• Token management -- create/list/revoke API tokens via CLI
• Single binary -- no runtime dependencies, SQLite embedded

API

Password-protected documents gate the human view, raw view, and full view. The agent API endpoint is not gated.

MCP Server

Twofold ships an MCP (Model Context Protocol) server for direct agent integration. Agents publish, retrieve, list, and delete documents without shelling out to curl.

twofold mcp

Runs on stdio (JSON-RPC, newline-delimited). Wire it into Claude Code or any MCP-compatible tool:

{
  "mcpServers": {
    "twofold": {
      "command": "/path/to/twofold",
      "args": ["mcp"],
      "env": {
        "TWOFOLD_MCP_SERVER": "http://localhost:3000",
        "TWOFOLD_MCP_TOKEN": "your-token"
      }
    }
  }
}

MCP Tools

Environment: TWOFOLD_MCP_SERVER (default http://localhost:3000), TWOFOLD_MCP_TOKEN (falls back to TWOFOLD_TOKEN).

Authoring Format

Two markers. That's it.

<!-- @agent -->
Content only agents see.
<!-- @end -->

Everything outside markers is visible to both humans and agents. Everything inside is agent-only.

A third marker pair hides content from ALL rendered views (human, full, and agent HTML) while keeping it in the raw source:

<!-- @instructions -->
Meta-instructions for agents reading raw source. Never rendered.
<!-- @end-instructions -->

Why HTML comments?

• Invisible in every markdown renderer that exists
• Any LLM can emit them without special tooling
• Graceful degradation: without twofold, it's just a markdown file
• No new syntax to learn, no preprocessing step

Markers must be on their own line. Inline <!-- @agent --> in a paragraph is not parsed as a marker. Whitespace inside is tolerated: <!-- @agent --> works.

Themes

Select via frontmatter:

---
theme: dark
---

Unknown theme names fall back to clean silently.

Webhooks

Configure a URL; twofold fires JSON on document lifecycle events.

export TWOFOLD_WEBHOOK_URL="https://your-service.com/hook"
export TWOFOLD_WEBHOOK_SECRET="your-hmac-secret"  # optional

Events: document.created, document.updated, document.deleted.

Payload:

{
  "event": "document.created",
  "timestamp": "2026-05-10T03:22:00Z",
  "document": {
    "slug": "q1-revenue",
    "title": "Q1 Revenue Report",
    "url": "http://localhost:3000/q1-revenue",
    "api_url": "http://localhost:3000/api/v1/documents/q1-revenue"
  }
}

When TWOFOLD_WEBHOOK_SECRET is set, requests include an X-Twofold-Signature: sha256=<hex> header (HMAC-SHA256 of the JSON body). Fire-and-forget: webhook failure never affects API responses.

Configuration

All config is via environment variables. No config files.

CLI

twofold serve                                    # Start server
twofold publish <file|-> --server URL --token T  # Publish document
twofold publish <file> --title "..." --slug X    # Publish with frontmatter flags
twofold list --server URL --token T              # List documents
twofold delete <slug> --server URL --token T     # Delete a document
twofold token create --name "deploy-bot"         # Create API token
twofold token list                               # List tokens
twofold token revoke --name "deploy-bot"         # Revoke token
twofold mcp                                      # Start MCP server (stdio)

Agent Discovery

Every HTML page includes a <link> tag pointing to the raw markdown API endpoint:

<link rel="alternate" type="text/markdown" href="/api/v1/documents/{slug}" title="Full document (markdown)">

Agents that parse HTML can find the full document without knowing the API URL structure.

What This Is NOT

Not a paste bin. Paste bins store text. Twofold renders authored dual-layer documents with theming, expiry, and access control.

Not a CMS. No user accounts. No editing UI. No database migrations to babysit. Publish via API, done.

Not content negotiation. Cloudflare and Vercel convert the same content between formats (HTML vs markdown vs plain text). Twofold serves different content to different consumers. The author writes both layers. The service routes them.

License

MIT