# Overview

**The AI-native markdown humans and agents write together.** Markbase is a shared workspace where you and the agents you already use read, write, comment on, and publish the same living documents — one source of truth for both.

## How it works

Three layers, one document:

1. **The doc** — plain markdown, fully versioned. *Your source of truth.*

2. **The collaborators** — you and your agents edit, comment, and resolve together, in real time, with exactly the access you grant. *Where the work happens.*

3. **The reach** — publish any doc as a clean public page, built for search and AI answers. *Where it goes.*

## What makes it AI-native

An agent isn't a bolt-on chat box on the side. It's a first-class collaborator: it reads the whole document, proposes precise edits instead of rewrites, leaves comments, and answers questions — so you and your agents never drift out of sync.

## Where to start

1. **Quick start** — connect Claude Code in under a minute.

2. **Use cases** — what teams build with it.

3. **Features** — the editor, commenting, versioning, and publishing.

# Quick start

Give **Claude Code** and **Claude Desktop** access to your docs in under a minute.

## 1. Install

```bash
npx @markbase/cli@latest mcp install
```

A browser opens — approve — then restart your app. This sets up **both Claude Code and Claude Desktop**; add `--claude-code` or `--desktop` to pick just one.

## 2. Try it

Ask Claude:

- *"List my Markbase docs."*

- *"In my roadmap doc, change 'draft' to 'ready'."*

- *"Leave a comment asking whether the budget is final."*

Claude now reads, edits, and comments on your docs — with exactly the access your key allows.

## 3. Keep it up to date

The worker keeps running the version it started with — publishing a new release doesn't restart it. To upgrade:

```bash
npx -y @markbase/cli@latest uninstall-service
npx -y @markbase/cli@latest install-service
```

The **Agents** page warns when your worker is offline or out of date.

# Use cases

Real workflows, start to finish. Each assumes you've connected Claude once — `npx @markbase/cli mcp install` — so it can read, edit, and comment on your docs.

## Draft, refine, and publish a page with Claude

**Goal:** a public page that reads well, ranks on Google, and gets cited by AI answers — written by you and Claude together.

1. **Draft.** Ask Claude: *"Create a doc titled 'X'. Draft a page with a one-line summary up top and H2 sections for A, B, and C."* You get a structured first draft in seconds.

2. **Refine in comments.** Highlight a passage and comment *"tighten this"* or *"add a comparison table here."* Then: *"Address my open comments."* Claude edits from the threads and resolves them.

3. **Fact-check together.** *"Turn the claims in section B into a bulleted list, and flag anything you're unsure about as a comment."*

4. **Publish.** Hit **Publish** — the doc goes live at a clean `/p/<slug>` URL with title, description, Open Graph, and schema.org JSON-LD, plus a sitemap entry.

5. **Get found.** Submit your `/sitemap.xml` in Google Search Console; AI crawlers (GPTBot, PerplexityBot, ClaudeBot) pick it up from robots.txt.

**Outcome:** a public, SEO- and GEO-ready page — and the doc stays editable, so you and Claude keep it current.

## Run a proposal or brainstorm with your team

**Goal:** go from blank page to a decision, with people and an agent in the same doc.

1. **Frame it.** Create a doc and ask Claude: *"Draft a proposal outline for X — problem, options, recommendation, open questions."*

2. **Brainstorm.** Teammates (and Claude) add ideas inline; use tabs to keep *Options* and *Notes* separate from the main proposal.

3. **Discuss in place.** Comment on specific lines instead of a side thread — *"I'd push back on option 2 because…"* Claude can weigh in: *"Summarize the disagreement on option 2 as a comment."*

4. **Decide.** Ask Claude: *"Write a Decision section capturing what we agreed and the owners."*

**Outcome:** the proposal, the discussion, and the decision all live in one versioned doc — no context lost across chats and threads.

## Keep stakeholders in sync

**Goal:** one shared surface between your team and a customer (or exec), always on the latest version.

1. **Write once.** Draft the update, spec, or plan with Claude: *"Draft a project update: shipped, in progress, risks, next steps."*

2. **Share with the right role.** Send a **guest link** (no account) or add them as a **commenter** — they can read and comment but not change your text.

3. **Handle feedback in place.** They comment on the exact line; you or Claude respond and resolve — *"Reply to the open comments with our answer."*

4. **Publish externally (optional).** For a public-facing page, **Publish to web** gives them a stable URL that always shows the current version.

**Outcome:** no more emailing doc versions around — everyone reviews and comments on the same living document.

# Integrations

Connect Markbase to the agent you already use. Today that's **Claude**; more are on the way.

## Claude

Claude Code and Claude Desktop connect over **MCP** (Model Context Protocol) — one command wires up both.

### Install

```bash
npx @markbase/cli@latest mcp install
```

A browser opens to sign you in (it mints and saves an API key), then configures **both** apps. To target one, add `--claude-code` or `--desktop`.

Under the hood it:

- **Claude Code** — registers a `markbase-docs` MCP server at user scope in `~/.claude.json` (via `claude mcp add`), so it's available in every project.

- **Claude Desktop** — adds `markbase-docs` to `claude_desktop_config.json` (on macOS, under `~/Library/Application Support/Claude/`).

### Verify

Restart the app, then ask Claude:

> *"List my Markbase docs."*

You should see your documents. In Claude Code you can also run `claude mcp list` and look for `markbase-docs … ✔ Connected`.

### What you can ask

- *"Read my roadmap doc."*

- *"In the roadmap, change 'draft' to 'ready'."*

- *"Leave a comment asking whether the budget is final."*

- *"What changed in this doc recently?"*

Claude acts as **you**, limited to the capability on your key — owner, editor, commenter, or viewer.

### Troubleshooting

- **Tools don't show up** — fully quit and reopen Claude Code / Desktop after installing.

- **"No API key"** — the installer signs you in; if you skipped it, set `MARKBASE_API_KEY` or re-run the command.

- **Claude Code was skipped** — the `claude` CLI wasn't on your PATH. Install Claude Code, then re-run `mcp install --claude-code`.

## Coming soon

- **Cursor**

- **Codex**

- **opencode**

- **pi**

- **openclaw**

# Features

## Editor

A WYSIWYG markdown editor over the same files your agents read — write visually, and it's plain markdown underneath.

- **Slash commands** — type `/` for a block menu: normal text, headings, bullet / numbered / task lists, quote, code block, table, divider, and today's date.

- **Formatting toolbar** — select any text for a bubble menu with bold, italic, strikethrough, highlight, inline code, links, and block types.

- **Links** — select text and click the link button to attach a URL; unlink from the same menu.

- **Tables** — insert a table with a header row and edit cells inline.

- **Reorder blocks** — grab a block by its drag handle to move it.

- **Autosave** — every change saves and syncs on its own; there's no save button.

### Keyboard shortcuts

| Action | Shortcut |
| --- | --- |
| Bold | ⌘/Ctrl + B |
| Italic | ⌘/Ctrl + I |
| Strikethrough | ⌘/Ctrl + Shift + S |
| Highlight | ⌘/Ctrl + Shift + H |
| Inline code | ⌘/Ctrl + E |
| Heading 1 / 2 / 3 | ⌘/Ctrl + Alt + 1 / 2 / 3 |
| Bullet list | ⌘/Ctrl + Shift + 8 |
| Numbered list | ⌘/Ctrl + Shift + 7 |
| Quote | ⌘/Ctrl + Shift + B |
| Block menu | / |
| Undo / Redo | ⌘/Ctrl + Z / ⌘/Ctrl + Shift + Z |

## Commenting

Comments are how people and agents discuss a doc without changing it.

- **Anchored to text** — highlight a passage and comment on it; the note stays pinned to that text and highlights it in the doc.

- **Threads** — reply to build a discussion, and mark it resolved when it's settled (toggle *Show resolved* to revisit).

- **Agents comment too** — an agent can ask you to clarify or flag a blocker right where it matters, instead of editing your words.

## Versioning

Every change is saved, so nothing is ever lost.

- **Full history** — open the history panel to see every version over time, and who changed what.

- **Restore** — roll back to any past version in a click; the rollback is itself a new version, so the current state is never lost.

- **Diff** — compare any two versions to see exactly what changed.

## Collaborating

People and agents work the same document at the same time.

- **Real-time** — edits sync live through an operation log, so two writers never clobber each other.

- **Tabs** — keep related sections in one document as tabs (say, a product design in one and an action plan in another).

- **Share** — invite members (they sign in) or hand out a guest link, and choose their role: editor, commenter, or viewer.

- **Per-agent access** — give an agent's API key a capability ceiling, so it can never do more than you allow.

## Publish to web

Turn any doc into a public page in one click.

- **One click** — the owner hits Publish and the doc goes live at a clean `/p/<slug>` URL; Unpublish takes it back offline.

- **Built for search + AI** — server-rendered semantic HTML with title, description, Open Graph, and schema.org JSON-LD, plus a sitemap and robots rules so Google and AI answers (ChatGPT, Perplexity, Claude) can find it.

- **Owner-only** — only the owner can publish or unpublish; collaborators can't.