# Markbase Help — Agent Index

This is the agent-facing index of `help.markbase.cloud`. Every link below
points to the raw Markdown of one help page, served at a stable URL on this
host. Use it as your table of contents when reasoning about Markbase.

Every page is also available as rendered HTML under `/humans/<section>/<slug>`
(for a human reader). The `.md` URLs below are the canonical agent-facing
form: plain Markdown, no chrome.

- Site root: <https://help.markbase.cloud/>
- Sitemap (HTML pages): <https://help.markbase.cloud/sitemap.xml>
- llms.txt: <https://help.markbase.cloud/llms.txt>

## Getting Started

- [What is Markbase?](/agents/getting-started/what-is-markbase.md) — One-page overview of the object model, MCP endpoint, and the semantics agents must respect (ETags, soft-delete, immutable revisions, `_markbase.md` walk).
- [Quickstart](/agents/getting-started/quickstart.md) — Minimum sequence of MCP calls to discover workspaces, read a doc, and write one back safely.
- [Creating Your Account](/agents/getting-started/creating-your-account.md) — How a user signs up (Google/GitHub OAuth) and how an agent first connects.
- [Core Concepts](/agents/getting-started/core-concepts.md) — Organization, workspace, document, folder, typed collection, reserved filenames.

## Workspaces

- [Creating a Workspace](/agents/workspaces/creating-a-workspace.md) — `create_workspace` (MCP) or dashboard, slug rules, template discovery and cloning.
- [Folders & Organization](/agents/workspaces/folders.md) — Folders are implicit; writing `a/b/c/doc.md` creates the path. Listing and walking.
- [Settings](/agents/workspaces/settings.md) — Workspace-level settings an agent can read.
- [Deleting a Workspace](/agents/workspaces/archiving.md) — Deletion is destructive; restore window and constraints.

## Documents

- [Writing Markdown](/agents/documents/writing-markdown.md) — Supported Markdown features and what is preserved on round-trip.
- [Frontmatter](/agents/documents/frontmatter.md) — YAML frontmatter rules, reserved keys, and how schemas validate it.
- [Revisions & History](/agents/documents/revisions.md) — Every write creates an immutable revision. Use `list_revisions` / `read_doc_at`.
- [Trash & Restore](/agents/documents/trash.md) — Soft-delete semantics, the 30-day window, and `restore_doc`.
- [Linking Between Docs](/agents/documents/linking.md) — `[[wiki-link]]` syntax and how internal references resolve.
- [Storing Files](/agents/documents/files.md) — Store non-Markdown files (xlsx, pdf, images, …) via the presigned `upload_file` / `download_file` handshake. Never rendered.

## Typed Collections

- [What are Typed Collections?](/agents/collections/overview.md) — A folder containing `_schema.md` becomes a typed collection of records.
- [Defining a Schema](/agents/collections/defining-schema.md) — `_schema.md` format: field types, requiredness, defaults.
- [Records & Frontmatter](/agents/collections/records.md) — How records are named (UUIDv7), `append_record` semantics, and field contracts.
- [Querying Records](/agents/collections/querying.md) — `query_records`: filters, ordering, pagination.
- [Validation Rules](/agents/collections/validation.md) — What causes a record write to be rejected and how errors are reported.

## _markbase.md

- [What is _markbase.md?](/agents/markbase-md/overview.md) — Per-folder instructions for agents working inside a subtree.
- [Workspace Conventions](/agents/markbase-md/workspace-conventions.md) — Root `_markbase.md`: workspace-wide conventions.
- [Per-Folder Instructions](/agents/markbase-md/per-folder.md) — Nested `_markbase.md` files and what they govern.
- [Composition Rules](/agents/markbase-md/composition.md) — Walk order (root-to-leaf), precedence, and conflict resolution.

## MCP Server

- [Installing the MCP Server](/agents/mcp/installing.md) — Endpoint URL and how to register Markbase in an MCP-capable client.
- [Authentication](/agents/mcp/authentication.md) — OAuth 2.1 + PKCE + DCR. No static tokens.
- [Available Tools](/agents/mcp/tools.md) — Full tool reference: parameters, return shape, and concurrency rules per tool.
- [Working with Claude](/agents/mcp/claude.md) — Setup notes for Claude Desktop, Claude Code, and the Claude API.
- [Working with Other Clients](/agents/mcp/other-clients.md) — Notes for other MCP clients (Cursor, Zed, Codex, ChatGPT Desktop, etc.).

## Search

- [Full-Text Search](/agents/search/full-text.md) — `search_docs`: query syntax and ranking.
- [Filtering by Folder](/agents/search/filtering.md) — Scoping a search to a workspace or subtree.

## Concurrency & Sync

- [ETags & Optimistic Locking](/agents/sync/etags.md) — Every `read_doc` returns an `etag`. Writes require `if_match` or `if_absent: true`.
- [Conflict Handling](/agents/sync/conflicts.md) — What a write conflict looks like and how to recover.

## Team & Access

- [Members & Roles](/agents/team/members-and-roles.md) — Roles and what each can do.
- [Invites](/agents/team/invites.md) — Invite flow.
- [Settings & Profile](/agents/team/settings.md) — User-level settings.

## Troubleshooting

- [Sign-In Issues](/agents/troubleshooting/sign-in.md) — Common OAuth/sign-in failures.
- [MCP Connection](/agents/troubleshooting/mcp-connection.md) — Diagnosing MCP transport, auth, and tool-list problems.
- [Common Errors](/agents/troubleshooting/common-errors.md) — Recognizing and recovering from the error codes the API returns.

## Reference

- [Glossary](/agents/reference/glossary.md) — Definitions for the terms used across these docs.