Elephant.md — Product Requirements Document

Codename: Project Tusk Version: 1.0 Status: Final Draft Date: February 2026 Author: Nick Brooks

Table of Contents

1. Vision & Thesis
2. Core Competencies
3. Problem Statement
4. Product Definition
5. User Personas
6. Information Architecture
7. Core Features
8. The CLI: tusk
9. Web Experience & Typography
10. Social Sharing & Virality
11. Growth & User Acquisition
12. Agent Integration (MCP)
13. VS Code Extension
14. Trust & Security
15. URL Design & Routing
16. Versioning Model
17. Ephemeral Sharing (Burn Links)
18. Discovery & Trending
19. System Architecture
20. Data Model
21. Business Model
22. Implementation Roadmap
23. Success Metrics
24. Risks & Mitigations
25. Open Questions

1. Vision & Thesis

An elephant never forgets.

Elephant.md is the universal markdown platform for the agentic era. It is to markdown what YouTube is to video and npm is to packages — a frictionless place to publish, share, discover, and consume structured context.

Core Thesis: Markdown has become the programming language of AI. Specs, skills, proposals, templates, runbooks — the documents that drive AI agents are all written in markdown. Yet there is no dedicated platform to share, version, and discover them. Elephant.md fills that gap.

Design Philosophy: Agent-First, Human-Approved.

The platform is built for AI agents as the primary interface. Agents discover, fetch, install, and even propose new content — all without the human needing to run commands or browse a website. Humans serve as curators, publishers, and approvers. The experience is so seamless that a developer simply works with their AI agent, and Elephant.md operates invisibly in the background.

• AI agents are the primary consumers — they discover and retrieve context via MCP, automatically and transparently.
• Humans are the publishers and approvers — they push content and approve agent-proposed publications.
• The web experience is for reading, sharing, and discovery when humans want to browse directly.

2. Core Competencies

These are the five things Elephant.md must be the undisputed best at. Every feature decision, every design tradeoff, every sprint prioritization filters through these. If we’re not winning on all five, we’re not shipping.

2.1 Best Markdown Readability — Especially on Mobile

This is the flagship. When someone opens an elephant.md link on their phone, the reaction should be “holy shit, this is beautiful.” Not “good for a markdown renderer” — beautiful, full stop. Better than Medium. Better than Substack. The typography, spacing, and rendering quality should be so far ahead of GitHub Gists, raw GitHub READMEs, and Notion shares that there is no comparison.

This is how we earn the right to exist. If the reading experience isn’t transcendent, nothing else matters.

2.2 Best Agent Experience

AI agents are our primary users. Connecting to Elephant.md via MCP should be effortless. Discovering relevant context should feel like the agent “just knows.” The semantic search must be fast, relevant, and deeply integrated into agent workflows. An agent should be able to go from “I need help with X” to “here’s the best community knowledge on X” in under a second.

2.3 Best Publishing Experience

tusk push and it’s live. Right-click in VS Code and it’s live. Zero friction between “I wrote something useful” and “it’s on the internet with a beautiful URL.” No config files, no build steps, no deploy pipelines. If publishing takes more than 10 seconds, we’ve failed.

2.4 Best Developer Experience

The CLI is fast, intuitive, and delightful. Commands are short. Output is clear. Error messages are helpful. The entire tool feels like it was made by someone who actually uses a terminal every day. No bloat, no unnecessary prompts, no “are you sure?” confirmations on non-destructive actions.

2.5 Best for Sharing with Non-Technical People

A developer shares an elephant.md link with their product manager, their designer, their CEO. That person taps the link on their phone. They see a gorgeous document. No signup wall. No cookie banner. No “view raw” confusion. No broken rendering. Just the content, presented with care. They read it, they get it, they close the tab. Zero friction.

This is how we win word-of-mouth. Every shared link is an advertisement for the platform — but only if the experience is flawless for the person who didn’t choose to use Elephant.md.

3. Problem Statement

3.1 The Fragmentation Problem

Developers and AI practitioners write markdown constantly — project specs, agent skills, coding standards, architectural decision records, onboarding guides. Today, this content is scattered across:

• GitHub Gists — ugly, developer-hostile UI, no discovery, no versioning story, no mobile optimization.
• Notion/Confluence — bloated, slow, walled gardens. Not designed for sharing outside an org.
• Raw GitHub repos — works for code, but markdown files are second-class citizens. No standalone viewing experience.
• Pastebin/HasteBin — designed for code snippets, not long-form documents. Zero trust model.

2.2 The Agent Context Problem

AI agents (Claude Code, Cursor, Windsurf, Copilot) lack a unified, secure repository for persistent context. There is no way to:

• Share a verified, trusted skill file with the community.
• Install a context document into an agent’s working memory with one command.
• Discover what the community considers best-practice for a given task.
• Trust that a shared document hasn’t been tampered with after publication.

2.3 The Trust Problem

Existing solutions like “ClawdHub” and unvetted Gist-sharing create real security risks. Malicious markdown files with embedded prompt injections can hijack AI agents. There is no registry with a layered trust model for markdown content.

4. Product Definition

3.1 What Elephant.md IS

• A markdown publishing and sharing platform — publish any .md file and get a clean, shareable URL.
• A context registry — a searchable, categorized index of markdown documents optimized for AI agent consumption.
• An MCP server — AI agents can connect directly to discover and retrieve documents via semantic search.
• A trust layer — content is immutably versioned, scanned for malicious patterns, and backed by author reputation.

3.2 What Elephant.md is NOT

• Not a wiki or collaborative editor (no real-time co-editing).
• Not a note-taking app (no local storage, no offline mode).
• Not a CMS or blogging platform (no themes, no custom domains).
• Not a code registry (markdown only — no executables, no binaries).

3.3 The One-Liner

Elephant.md — Publish, share, and discover markdown. For humans and AI agents.

5. User Personas

4.1 Primary: The AI Agent

• The most frequent interface to Elephant.md. Connects via MCP.
• Discovers and retrieves context documents autonomously during task execution.
• Can propose new publications (drafts) that the human approves.
• Requires structured metadata (category, tags, compatibility) for filtering.
• Must trust that content is safe and unmodified.

4.2 Secondary: The AI-Native Developer

• Uses Claude Code, Cursor, or Windsurf daily.
• Writes markdown skills, project specs, and coding standards.
• Rarely interacts with Elephant.md directly — their agent handles it.
• Approves agent-proposed publications. Occasionally runs tusk push for manual uploads.
• Browses the web experience when they want to discover content themselves.

4.3 Tertiary: The Context Creator

• Writes premium skills, templates, and guides for AI workflows.
• Wants to monetize expertise (e.g., “My Claude Code skill for React optimization”).
• Needs a marketplace with built-in payments and audience.

4.4 Future: The Enterprise Team

• Needs private, SSO-protected document repositories.
• Wants organizational memory that persists across team members and AI agents.
• Requires audit logs and access controls.

6. Information Architecture

5.1 Content Categories (Fixed Taxonomy)

All documents belong to exactly one top-level category:

5.2 Tagging

Within each category, authors apply free-form tags. Tags are lowercase, hyphenated strings (e.g., react, claude-code, typescript, devops).

The platform maintains a list of promoted tags based on usage frequency, displayed during publishing to encourage consistency.

5.3 Visibility Levels (YouTube Model)

7. Core Features

6.1 Publish

Push any markdown file to Elephant.md and receive a permanent, versioned URL.

• Input: A .md file (via CLI, VS Code, or web upload).
• Output: A URL (elephant.md/user/doc-name or elephant.md/hash).
• Metadata captured: Title (from first # heading or filename), category, tags, author, timestamp, content hash.
• Default visibility: Unlisted.

6.2 Share

Share any document via its URL. The recipient sees a polished, mobile-optimized rendering.

• One-tap copy: Floating action button to “Copy Markdown” or “Send to Agent.”
• Embed support: OG meta tags and Twitter cards for rich link previews.
• QR code generation: For in-person sharing (conferences, meetups).

6.3 Discover

Browse and search the public document registry.

• Full-text search across titles, content, and tags.
• Category filtering by the fixed taxonomy.
• Trending — real-time momentum scores based on views, copies, and installs.
• Curated collections — editorially promoted sets of documents (e.g., “Best Claude Code Skills This Week”).

6.4 Install (Agent Injection)

One-command installation of a document into an AI agent’s context directory.

tusk install elephant.md/nick/react-skill

• Auto-detects the local AI environment (Claude Code, Cursor, Windsurf).
• Places the document in the correct agent-read directory.
• Pins the installed version by hash.
• Notifies the user when an update is available (never auto-updates).

6.5 Burn (Ephemeral Sharing)

Create time-limited links for sensitive documents (specs, proposals, internal data).

• Author sets an expiration duration (1 hour, 24 hours, 7 days, 30 days).
• After expiration, the content is permanently deleted from R2 storage.
• The URL returns a “This document has expired” page.
• Burn links are always unlisted (never indexed).

8. The CLI: tusk

7.1 Overview

tusk is the primary developer interface. It is distributed as a scoped npm package (@elephant/tusk) and symlinks to the 4-letter command tusk.

npm install -g @elephant/tusk

7.2 Authentication

tusk login

Opens a browser for GitHub or Google OAuth. Stores a session token locally at ~/.tusk/config.json.

7.3 Commands

tusk push <file> [options]

Publishes a markdown file to the registry.

Output:

Pushed successfully.
URL:    elephant.md/nick/react-skill
Hash:   a3f8b2c1
Size:   2.4 KB

tusk pull <url-or-hash>

Downloads a document to the current directory.

tusk pull elephant.md/nick/react-skill
# Downloads react-skill.md to ./

tusk install <url-or-hash>

Smart-installs a document into the local AI agent’s context directory.

tusk install elephant.md/nick/react-skill
# Detected: Claude Code
# Installed to: .claude/skills/react-skill.md (pinned: a3f8b2c1)

Agent detection logic:

tusk update [--all]

Checks for newer versions of installed documents and prompts for update.

tusk update
# react-skill: a3f8b2c1 → b7d2e4f8 (updated 2 hours ago)
# Update? [y/N]

tusk list

Lists all documents published by the authenticated user.

tusk trending [--category <cat>]

Shows currently trending public documents.

tusk trending --category skills
# 1. 🔥 @sarah/claude-typescript-strict (↑ 342 installs today)
# 2. 🔥 @mike/cursor-react-patterns    (↑ 218 installs today)
# 3.    @lisa/windsurf-python-lint      (↑ 156 installs today)

tusk search <query>

Full-text search across public documents.

tusk burn <file> --ttl <duration>

Shorthand for tusk push <file> --burn <duration>. Creates a time-limited ephemeral link.

tusk burn spec.md --ttl 24h
# Burn link: elephant.md/b/x8k2m (expires in 24 hours)

tusk whoami

Shows the current authenticated user and their trust tier.

9. Web Experience & Typography

9.1 Design Philosophy: Reading is the Product

The document viewer is Elephant.md’s most important surface. Every shared link lands here. This is where non-technical people form their opinion of the platform in 3 seconds. The reading experience must be so good that people notice it — that they screenshot it, that they say “what is this? it looks amazing.”

We are not building a markdown renderer with nice CSS. We are building the best reading experience for technical documents on the internet, period.

9.2 Typography Specification

Typeface System:

Spacing & Sizing (Mobile-First):

Rendering Details:

• Font loading: Preload critical fonts. Use font-display: swap with a carefully matched system font fallback to eliminate layout shift. Test on 3G throttle.
• Hyphenation: CSS hyphens: auto for body text. Prevents ugly ragged right edges on mobile.
• Orphan/widow control: CSS orphans: 2; widows: 2 to prevent single lines at page breaks.
• Smart quotes: Render straight quotes as curly quotes. Render -- as en-dash, --- as em-dash.
• Ligatures: Enable in code blocks (font-variant-ligatures: contextual).

Dark Mode:

• System-preference-aware (prefers-color-scheme).
• Manual toggle via subtle icon in the document header (sun/moon).
• Dark mode is NOT just “invert colors.” Carefully chosen dark palette:

- Background: #1a1a2e (deep blue-black, not pure black — easier on eyes) - Text: #e0e0e0 (soft white, not pure white — reduces contrast glare) - Code blocks: #0d1117 (GitHub-dark inspired) - Links: #8ab4f8 (soft blue)

Markdown Element Rendering:

• Tables: Zebra-striped, horizontally scrollable on mobile, with sticky first column for wide tables.
• Images: Lazy-loaded, max-width 100%, subtle border-radius, click-to-zoom on mobile.
• Blockquotes: Left border + slight background tint. Italic body text. Feels like a pull-quote.
• Horizontal rules: Subtle, centered, short (40% width). Not a full-width line.
• Lists: Generous spacing between items. Nested lists with distinct markers (disc → circle → square).
• Task lists: Rendered as styled checkboxes (not browser defaults).
• Footnotes: Superscript numbers with smooth scroll-to-footnote behavior.

9.3 Document Viewer (elephant.md/<user>/<doc>)

The Rules:

1. Nothing between the user and the content. No signup wall. No cookie banner. No popups. No interstitial.
2. The elephant.md logo is present but unobtrusive — a small mark in the top-left corner, clickable to the homepage. It establishes brand without interrupting reading.
3. The page loads fast. Target: First Contentful Paint under 500ms on 4G. The markdown is server-side rendered at the edge — no client-side JS required for the initial read.

Page Layout (Mobile):

┌──────────────────────────────┐
│ 🐘  elephant.md     [☀/🌙]  │  ← Tiny header: logo + dark mode toggle
├──────────────────────────────┤
│                              │
│  Document Title              │  ← h1, large, serif
│                              │
│  @author · Skills · v3       │  ← Author, category badge, version
│  2 days ago · 1.2k installs  │  ← Recency + social proof
│                              │
│  ─────────                   │  ← Subtle separator
│                              │
│  Body text flows here with   │
│  beautiful typography and    │
│  generous spacing. The       │
│  reading experience is       │
│  indistinguishable from a    │
│  premium publication.        │
│                              │
│  ## Subheading               │
│                              │
│  More content...             │
│                              │
│  ```typescript               │
│  const x = await fetch()     │
│  ```                         │
│                              │
│  ...                         │
│                              │
├──────────────────────────────┤
│  [Copy MD] [Install] [Share] │  ← Floating action bar (fixed bottom)
└──────────────────────────────┘

Floating Action Bar (fixed to bottom of viewport):

• Semi-transparent background with backdrop blur. Slides up on scroll-down, reappears on scroll-up.
• Three buttons maximum — no clutter:

- Copy Markdown — copies raw .md source to clipboard. Toast confirmation: “Copied.” - Install — copies tusk install elephant.md/user/doc to clipboard. Toast: “Install command copied.” - Share — native Web Share API on mobile, copy-URL on desktop.

• A small “…” overflow menu for: Report, View Raw, Version History.

Page Layout (Desktop):

• Content centered at 680px max-width.
• Large margins on both sides (the whitespace IS the design).
• Floating action bar repositions to a subtle sidebar or inline buttons at the bottom of the document.

9.4 Author Profile (elephant.md/<user>)

• Avatar, display name, bio, GitHub link.
• Trust tier badge (New, Verified, Trusted, Matriarch).
• List of public documents, sortable by recent/popular.
• Total installs and views across all documents.
• Clean grid or list layout — same typographic quality as the document viewer.

9.5 Explore Page (elephant.md/explore)

• Trending Now — top documents by momentum score. Card-based layout with title, author, category, and install count.
• Category browsing — horizontal filter pills (Skills, Specs, Templates, Guides, Data, Standards).
• Staff Picks — editorially curated collections.
• Recently Published — chronological feed of new public documents.
• Search bar prominent at top with instant-search (typeahead results as you type).

9.6 Homepage (elephant.md)

• Hero: tagline + “Get Started” CTA. Clean, bold, no visual noise.
• Live trending ticker showing top documents (animated, subtle).
• Quick-start code block: npm install -g @elephant/tusk.
• Social proof: install counts, user counts, agent integration logos (Claude, Cursor, Windsurf).
• One example document rendered inline at full quality — “See it in action.” This is the most persuasive element: show, don’t tell.

10. Social Sharing & Virality

10.1 The Core Loop

Every elephant.md link shared on X, Slack, Discord, or iMessage is a free advertisement. The virality loop is:

Developer pushes doc → Shares link on X → Beautiful card catches attention →
Reader clicks → Stunning reading experience → Reader shares it too →
Some readers become publishers → Cycle repeats

This loop is the primary growth engine. It must be optimized obsessively.

10.2 Open Graph & Social Cards

When an elephant.md link is shared on any platform, the preview card must stop the scroll.

Card Type: Visual Screenshot + Rich Text Preview

The OG image is dynamically generated per document — not a generic Elephant.md card. It is a beautiful, high-fidelity screenshot of the document’s opening lines, rendered with our premium typography.

OG Image Specification:

• Size: 1200x630px (optimal for X/Twitter large card).
• Content: First ~4-6 lines of the document, rendered with our actual fonts (Lora body, JetBrains Mono code).
• Background: Clean white (light mode) or deep dark (dark mode based on user preference).
• Branding: Small elephant.md wordmark in the bottom-right corner. Author avatar + username in the bottom-left.
• Category badge: Colored pill (e.g., “Skill” in teal, “Spec” in purple) in the top-right corner.

Generation Pipeline:

• OG images are generated on first request using a Cloudflare Worker + @vercel/og (Satori) or Puppeteer-based screenshot service.
• Cached in R2 and served from the edge. Regenerated when the document is updated.
• Fast: target < 200ms generation time, < 50ms on cache hit.

Meta Tags:

<meta property="og:title" content="React TypeScript Strict Mode Skill" />
<meta property="og:description" content="A Claude Code skill that enforces strict TypeScript patterns..." />
<meta property="og:image" content="https://elephant.md/og/nick/react-skill.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:type" content="article" />
<meta property="og:site_name" content="Elephant.md" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@elephantmd" />

10.3 Platform-Specific Optimization

10.4 Share Mechanics from the Document Viewer

Mobile “Share” button behavior:

1. Triggers the native Web Share API (navigator.share()).
2. Shares the clean URL (elephant.md/nick/react-skill) + document title.
3. Fallback for browsers without Web Share: copy URL to clipboard with toast.

“Copy for X” option (in overflow menu):

• Copies a pre-formatted tweet: "[Document Title]" by @author — elephant.md/nick/react-skill
• Short, clean, no hashtag spam. The OG card does the heavy lifting.

10.5 Embed Support

For blogs, docs sites, and README files:

<!-- iframe embed with responsive sizing -->
<iframe src="https://elephant.md/nick/react-skill/embed"
        style="width:100%;height:400px;border:none;border-radius:8px;">
</iframe>

The embed view strips the header and footer, showing only the beautifully rendered content with a subtle “View on elephant.md” link at the bottom.

11. Growth & User Acquisition

11.1 Strategy: Content-Led Virality

Elephant.md does not grow through paid ads or cold outreach. It grows because the content itself is the marketing. Every shared document is an on-ramp to the platform.

11.2 Acquisition Channels

Channel 1: X / Twitter (Primary)

The AI developer community lives on X. This is where skills go viral, where new tools are discovered, where opinions form.

Tactics:

• Make sharing irresistible: The OG card is so beautiful that sharing an elephant.md link makes the sharer look good. Developers will prefer sharing an elephant.md link over a raw Gist URL because it looks better in their timeline.
• Seed with influencers: Identify the top 50 AI developer accounts on X. Personally onboard them. Give them “Matriarch” status. Their shares seed the algorithm.
• “Published on Elephant.md” as a status signal: Like “built with Vercel” or “powered by Stripe” — make it a mark of quality to have your skills on Elephant.md.
• @elephantmd account: Share trending skills daily. Retweet community content. Build the brand account as a discovery channel itself.

Channel 2: GitHub / Dev Communities

• README badges: — embed in project READMEs linking to context docs.
• Awesome lists: Create and maintain awesome-elephant-skills repo. Get listed in awesome-claude, awesome-cursor, etc.
• Dev.to / Hashnode: “How I share my AI agent skills with Elephant.md” tutorial posts.

Channel 3: Word of Mouth via Reading Experience

This is the silent engine. When a developer shares a spec with a PM via Elephant.md and the PM says “wow this looks great, what is this?” — that’s acquisition. No marketing spend required.

Key metric: organicreferralrate — % of new signups that came from clicking the logo on a shared document.

Channel 4: Agent-Native Discovery

As MCP adoption grows, agents will recommend Elephant.md content to users who don’t know the platform exists. “I found a relevant skill on Elephant.md — want me to install it?” This is the long-game flywheel.

11.3 Onboarding Flow

The path from “I just heard about this” to “I published my first document” must be under 5 minutes.

1. User arrives at elephant.md (from X link, word of mouth, etc.)
2. "Get Started" → tusk install instructions (one command)
3. tusk login → GitHub OAuth (one click)
4. tusk push my-skill.md → Published. URL in clipboard.
5. User shares URL on X → Beautiful card → Loop continues

No onboarding wizard. No tutorial. No “complete your profile” nag. Push first, polish profile later. The first push is the activation moment — get there fast.

11.4 Retention Hooks

• Update notifications: “Your installed skills have updates” keeps users coming back.
• Trending notifications: “Your skill is trending!” — dopamine hit for publishers.
• Agent proposals: “Claude wants to publish a new document” — pulls users back to approve.
• Weekly digest email (opt-in): Top trending documents in your categories. Light, scannable, one-click to read.

12. Agent Integration (MCP)

9.1 Overview

Elephant.md operates as a Model Context Protocol (MCP) server that AI agents can connect to directly. This enables agents to discover, search, and retrieve documents without human intervention.

9.2 MCP Server Capabilities

Resources

Tools

9.3 Agent Publishing (Human-Approved)

Agents can propose new publications, but humans must approve before content goes live. This creates a flywheel where agents generate context from their work, but humans maintain quality control.

Flow:

1. Agent calls the propose MCP tool with markdown content, suggested title, category, and tags.
2. Elephant.md stores the draft in a pending state (not publicly accessible).
3. The author receives a notification (email, VS Code notification, or CLI alert on next tusk command).
4. The author reviews the draft: approve (publishes), edit + approve, or reject.
5. Approved content is published under the author’s namespace.

Use Cases:

• Claude Code finishes refactoring a codebase and proposes a “Lessons Learned” document.
• An agent discovers a useful pattern during a task and proposes it as a reusable skill.
• An agent drafts a post-mortem or architectural decision record after resolving a complex bug.

Safeguards:

• Agent-proposed content is subject to the same security scanning as human pushes.
• Pending drafts auto-expire after 7 days if not reviewed.
• Rate limit: max 5 proposals per agent per day per user account.
• Agent-published content is tagged with agent-proposed for transparency.

9.4 Semantic Discovery

The discover tool is the key differentiator for agent integration.

How it works:

1. Agent sends a natural language description: “I need a skill that helps me write idiomatic Rust with proper error handling.”
2. Elephant.md computes an embedding of the query.
3. Vector similarity search against pre-computed document embeddings.
4. Returns top-N results ranked by relevance, each with metadata and a snippet.

Embedding pipeline:

• Documents are embedded on push using a lightweight model (e.g., text-embedding-3-small).
• Embeddings are stored alongside documents in the metadata database.
• Query embeddings are computed at request time at the edge.

9.5 MCP Configuration

Agents connect to Elephant.md by adding it to their MCP configuration:

{
  "mcpServers": {
    "elephant": {
      "url": "https://mcp.elephant.md/sse",
      "transport": "sse"
    }
  }
}

tusk install --mcp auto-configures this for the detected agent.

13. VS Code Extension

10.1 Overview

A lightweight VS Code extension (elephant.vscode) providing frictionless publish-from-editor.

10.2 Features

• Right-click publish: Right-click any .md file in the explorer → “Publish to Elephant.md.” Opens a quick-pick for category, tags, and visibility.
• Inline status: Published files show a small elephant icon in the editor tab with the live URL.
• Push on save (opt-in): Auto-push updates to Elephant.md when a tracked .md file is saved.
• Pull into editor: Command palette → “Elephant: Pull Document” → paste a URL → opens in editor.
• Gutter indicators: Show which local .md files are tracked by Elephant.md and whether they have unpushed changes.

10.3 Authentication

Uses the same ~/.tusk/config.json session token as the CLI. If not logged in, prompts to run tusk login.

14. Trust & Security

11.1 Layered Defense Model

Security is a core differentiator. Elephant.md implements defense-in-depth against malicious markdown and prompt injection attacks.

Layer 1: Automated Scanning (On Push)

Every document is scanned before it becomes accessible:

• Prompt injection detection: Pattern matching against known injection techniques (e.g., “ignore previous instructions,” hidden Unicode characters, base64-encoded payloads).
• Content policy check: Scan for malware links, phishing URLs, and prohibited content.
• Structure validation: Ensure the file is valid markdown (not a renamed binary, not excessively large).

Action on detection: Block the push and return a detailed error. The document is not stored.

Layer 2: Community Reporting

• Every document has a “Report” button in the web viewer.
• Reports are triaged by category: prompt injection, spam, malware, copyright, other.
• Documents with multiple reports are auto-hidden pending review.
• False reporters lose reputation; valid reporters gain reputation.

Layer 3: Tiered Trust (Reputation System)

11.2 Proof of Personhood

Account creation requires:

• GitHub or Google OAuth (no anonymous accounts).
• Email verification.
• Optional but incentivized: 2FA enrollment (boosts trust tier faster).

11.3 Immutability Guarantees

• Every version of a document is stored by its content hash (SHA-256).
• Published content cannot be silently modified. A new push creates a new version with a new hash.
• Consumers who pin a hash are guaranteed to receive the exact content they expect.
• The “latest” named URL always resolves to the newest version, but the hash is displayed so consumers can verify.

15. URL Design & Routing

12.1 URL Structure

12.2 Slug Rules

• Derived from filename by default (e.g., react-skill.md → react-skill).
• Lowercase, alphanumeric + hyphens only. Max 64 characters.
• Must be unique per user (can be reused across users).
• Reserved slugs: settings, explore, trending, api, login, signup, etc.

12.3 Content Negotiation

The same URL serves different content based on the Accept header:

This means curl elephant.md/nick/react-skill with the right header returns raw markdown — useful for piping into agents or scripts.

16. Versioning Model

13.1 Immutable Versions

Every tusk push creates a new immutable version identified by the first 8 characters of a SHA-256 hash of the content.

v1: a3f8b2c1 (created Feb 23, 2026)
v2: b7d2e4f8 (created Feb 25, 2026)  ← latest

13.2 Named References

The named URL (elephant.md/nick/react-skill) always resolves to the latest version. The response includes the current hash in a header and in the rendered page so consumers know exactly what they’re getting.

13.3 Pinned References

Consumers who need stability can pin to a specific version:

tusk install elephant.md/nick/react-skill@a3f8b2c1

This installs the exact content at hash a3f8b2c1, regardless of any newer versions.

13.4 Update Notifications

When a document has a newer version:

• tusk update shows the diff between pinned and latest.
• The web viewer shows a banner: “A newer version of this document is available.”
• The MCP server includes has_update: true in metadata responses.

Critical: Updates are never applied automatically. The consumer must explicitly choose to update. This prevents bait-and-switch attacks where an author publishes a benign document, gains installs, then pushes a malicious update.

17. Ephemeral Sharing (Burn Links)

14.1 Overview

Burn links provide time-limited sharing for sensitive content — internal specs, client proposals, competitive analysis, interview materials.

14.2 Mechanics

• Creation: tusk burn spec.md --ttl 24h or via web upload.
• Duration options: 1 hour, 24 hours, 7 days, 30 days.
• Storage: Content is stored in R2 with an expiration metadata tag.
• Cleanup: A scheduled Cloudflare Worker runs hourly to permanently delete expired content.
• URL format: elephant.md/b/<random-id> — short, unguessable IDs (12-character base62).

14.3 User Experience

• Burn links display a countdown timer in the document header: “This document expires in 23h 42m.”
• After expiration, the URL returns a tombstone page: “This document has expired and been permanently deleted.”
• Burn links are always unlisted — never indexed, never appear in search or trending.
• No view counter (to avoid leaking access information for sensitive docs).

14.4 Limitations

• Burn links cannot be versioned (single push, no updates).
• Maximum file size for burn links: 100 KB (prevents abuse).
• Burn links do not support the MCP layer (not discoverable by agents).

18. Discovery & Trending

15.1 Momentum Score

Every public document has a real-time momentum score that powers the trending algorithm.

Inputs:

Formula: Momentum = Σ (weight × e^(-t/decay)) for all events in the last 7 days.

15.2 Analytics Pipeline

Events → Cloudflare Logpush → BigQuery → Momentum Score API

• All user interactions are logged to Cloudflare Logpush.
• Logpush streams to BigQuery in near-real-time.
• A scheduled query (every 5 minutes) recalculates momentum scores.
• Scores are cached at the edge (Cloudflare KV) for sub-10ms retrieval.

15.3 Anomaly Detection

BigQuery runs anomaly detection to identify:

• Bot traffic: Sudden spikes in views/installs from single IPs or user agents.
• Self-promotion abuse: Authors inflating their own metrics.
• Coordinated manipulation: Multiple accounts boosting a single document.

Detected anomalies trigger automatic score adjustment and flag the account for review.

19. System Architecture

16.1 Infrastructure Stack

All infrastructure runs on Cloudflare’s edge network for sub-50ms global latency.

┌─────────────────────────────────────────────────────┐
│                    Clients                           │
│  CLI (tusk)  │  VS Code  │  Web Browser  │  AI Agent │
└──────┬───────┴─────┬─────┴──────┬────────┴─────┬────┘
       │             │            │              │
       ▼             ▼            ▼              ▼
┌─────────────────────────────────────────────────────┐
│              Cloudflare Workers (Edge)               │
│                                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ API      │  │ Web      │  │ MCP      │          │
│  │ Router   │  │ Renderer │  │ Server   │          │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       │              │              │                │
│  ┌────▼──────────────▼──────────────▼────┐          │
│  │         Auth / Trust Middleware        │          │
│  └────┬──────────────┬──────────────┬────┘          │
└───────┼──────────────┼──────────────┼───────────────┘
        │              │              │
   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
   │   R2    │   │   D1    │   │   KV    │
   │ (Files) │   │ (Meta)  │   │ (Cache) │
   └─────────┘   └─────────┘   └─────────┘
        │              │
        │              ▼
        │        ┌──────────┐
        │        │ Vectorize│
        │        │(Embeddings)│
        │        └──────────┘
        │
        ▼
   ┌──────────┐
   │ Logpush  │───▶ BigQuery (Analytics)
   └──────────┘

16.2 Component Responsibilities

16.3 Request Flow: tusk push

1. CLI reads .md file, computes SHA-256 hash
2. CLI sends POST /api/v1/documents with auth token, file content, metadata
3. Worker validates auth token → D1 lookup
4. Worker runs content security scan (prompt injection, policy check)
5. Worker stores file in R2 at key: documents/{hash}
6. Worker computes embedding → stores in Vectorize
7. Worker upserts metadata in D1 (slug, category, tags, hash, timestamp)
8. Worker returns { url, hash, size } to CLI

16.4 Request Flow: Web View

1. Browser requests elephant.md/nick/react-skill
2. Worker parses URL → looks up slug in D1 → gets latest hash
3. Worker fetches content from R2 by hash (KV cache check first)
4. Worker renders markdown to HTML with typography template
5. Returns HTML with OG tags, floating action bar, author header

20. Data Model

17.1 D1 Schema

-- Users
CREATE TABLE users (
  id TEXT PRIMARY KEY,              -- UUID
  username TEXT UNIQUE NOT NULL,     -- URL-safe slug
  display_name TEXT,
  email TEXT UNIQUE NOT NULL,
  avatar_url TEXT,
  bio TEXT,
  github_id TEXT UNIQUE,
  google_id TEXT UNIQUE,
  trust_tier INTEGER DEFAULT 0,     -- 0=New, 1=Verified, 2=Trusted, 3=Matriarch
  two_factor_enabled BOOLEAN DEFAULT FALSE,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

-- Documents (metadata only; content lives in R2)
CREATE TABLE documents (
  id TEXT PRIMARY KEY,              -- UUID
  user_id TEXT NOT NULL REFERENCES users(id),
  slug TEXT NOT NULL,               -- URL slug
  title TEXT NOT NULL,
  category TEXT NOT NULL,           -- skills, specs, templates, guides, data, standards
  visibility TEXT DEFAULT 'unlisted', -- private, unlisted, public
  latest_hash TEXT NOT NULL,        -- SHA-256 hash of current version
  description TEXT,                 -- Short description for search results
  install_count INTEGER DEFAULT 0,
  view_count INTEGER DEFAULT 0,
  copy_count INTEGER DEFAULT 0,
  is_burn BOOLEAN DEFAULT FALSE,
  burn_expires_at TEXT,             -- ISO 8601 timestamp
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(user_id, slug)
);

-- Document versions
CREATE TABLE versions (
  hash TEXT PRIMARY KEY,            -- SHA-256 content hash
  document_id TEXT NOT NULL REFERENCES documents(id),
  size_bytes INTEGER NOT NULL,
  created_at TEXT NOT NULL
);

-- Tags
CREATE TABLE document_tags (
  document_id TEXT NOT NULL REFERENCES documents(id),
  tag TEXT NOT NULL,
  PRIMARY KEY (document_id, tag)
);

-- Reports
CREATE TABLE reports (
  id TEXT PRIMARY KEY,
  document_id TEXT NOT NULL REFERENCES documents(id),
  reporter_id TEXT NOT NULL REFERENCES users(id),
  reason TEXT NOT NULL,             -- prompt_injection, spam, malware, copyright, other
  details TEXT,
  status TEXT DEFAULT 'pending',    -- pending, reviewed, actioned, dismissed
  created_at TEXT NOT NULL
);

-- Installs (for update notification tracking)
CREATE TABLE installs (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES users(id),
  document_id TEXT NOT NULL REFERENCES documents(id),
  pinned_hash TEXT NOT NULL,
  agent_type TEXT,                  -- claude, cursor, windsurf, generic
  created_at TEXT NOT NULL,
  UNIQUE(user_id, document_id)
);

-- Agent-proposed drafts (pending human approval)
CREATE TABLE drafts (
  id TEXT PRIMARY KEY,              -- UUID
  user_id TEXT NOT NULL REFERENCES users(id),
  title TEXT NOT NULL,
  content_hash TEXT NOT NULL,       -- SHA-256 of draft content (stored in R2 at drafts/{hash})
  suggested_slug TEXT,
  suggested_category TEXT,
  suggested_tags TEXT,              -- JSON array of tag strings
  agent_type TEXT,                  -- Which agent proposed this
  status TEXT DEFAULT 'pending',    -- pending, approved, rejected, expired
  expires_at TEXT NOT NULL,         -- Auto-expire after 7 days
  created_at TEXT NOT NULL,
  reviewed_at TEXT
);

17.2 R2 Object Layout

documents/{hash}          -- Raw markdown content, keyed by SHA-256
avatars/{user_id}         -- User profile images

17.3 KV Namespace Layout

trending:{category}       -- JSON array of top 50 document IDs + scores
session:{token}           -- User ID for session validation
ratelimit:{user_id}:{action} -- Rate limit counters with TTL

21. Business Model

18.1 Philosophy

Free for individuals, forever. Monetize through marketplace commission and enterprise features. Prioritize growth velocity over revenue in the first 90 days.

18.2 Free Tier (All Users)

• Unlimited unlisted documents.
• Up to 50 public documents.
• 10 MB per document.
• 5 burn links per day.
• Full CLI and VS Code extension access.
• Full MCP server access for agents.

18.3 Revenue Stream 1: Marketplace (“Tusk Tax”)

• Authors can set a price on public documents (minimum $1, maximum $99).
• Purchasers get permanent access to the document and all future versions.
• Elephant.md takes a 10% commission on all transactions.
• Payments processed via Stripe Connect (authors receive direct payouts).
• Only Matriarch tier users can sell (quality gate).

18.4 Revenue Stream 2: Enterprise “Herd” Plans

18.5 Cost Structure

All infrastructure is Cloudflare, which provides aggressive free tiers:

Estimated monthly cost at 10K active users: < $50/mo.

22. Implementation Roadmap

Phase 1: Foundation + MCP (Days 1-14)

Goal: Core infrastructure, CLI push/pull, basic web rendering, AND a working MCP server. CLI and MCP ship together because agents are the primary interface.

Phase 2: Agent Depth & Publishing Polish (Days 15-30)

Goal: Semantic MCP search, burn links, VS Code extension, agent publishing.

Phase 3: Discovery & Growth (Days 31-60)

Goal: Trending, explore page, community features, reputation system.

Phase 4: Monetization & Scale (Days 61-90)

Goal: Marketplace, team features, exit prep.

23. Success Metrics

20.1 North Star Metric

Monthly Active Pushes (MAP): Total number of unique documents published per month. This measures the core value loop — people creating and sharing markdown.

20.2 Growth Metrics

20.3 Engagement Metrics

20.4 Trust Metrics

23.5 Virality & Sharing Metrics

23.6 Acquisition-Readiness Metrics

24. Risks & Mitigations

24.1 Technical Risks

24.2 Product Risks

24.3 Business Risks

25. Open Questions

These items require further research or decisions during implementation:

1. Username namespace: Should we reserve common usernames (e.g., react, python, aws) for official/verified org accounts? How do we handle squatting?

1. Content licensing: What license applies to published documents by default? Should authors choose from a set of licenses (CC-BY, MIT, etc.), or is there a platform-wide default?

1. Document size limits: What’s the maximum file size for non-burn documents? 10 MB feels generous but needs validation against R2 and Worker memory limits.

1. Import tools: Should we build a tusk import-gist <url> command to help users migrate existing content? What about importing from GitHub repos?

1. Collaborative editing: The spec explicitly excludes real-time co-editing, but should multiple team members be able to push updates to the same document? If so, how are conflicts handled?

1. Offline support: Should the CLI cache recently pulled documents for offline access? How fresh does the cache need to be?

1. Rate limiting specifics: What are the exact rate limits per trust tier? How do we balance abuse prevention with legitimate high-volume usage?

1. International content: Do we support non-English markdown? How does this affect search, trending, and content scanning?

1. API versioning strategy: How do we handle breaking changes to the REST API and MCP interface over time?

1. Content moderation at scale: At what user count do we need human moderators vs. automated-only moderation? What’s the escalation path?

This document is the source of truth for the Elephant.md product. All implementation decisions should reference this spec. Update this document as decisions are made on open questions.

Last updated: February 23, 2026