---
name: notdocs
description: Set up and use notdocs, a workspace whose documents are markdown files in the git repository. Use when asked to add notdocs to a repository, connect its MCP server, or read and write specs, tasks, decisions and other notdocs documents.
---

# notdocs

notdocs keeps pages, tasks, decisions and specs as markdown files with YAML frontmatter in a git repository. People edit them in a web workspace; agents edit the same files over MCP or the `notdocs` CLI. Nothing syncs: every edit is a change to a file.

Docs: https://entro314.notdocs.dev/notdocs-docs/p · Agents: https://notdocs.dev/agents · CLI: https://notdocs.dev/cli

## Set up in a repository

1. Install the CLI (Node 24 or later): `npm install -g notdocs`, or prefix each command with `npx`.
2. Initialise the repository: `notdocs init .`. It writes `notdocs.config.json`, a `docs/` folder with starter documents, and a short notdocs section in the `CLAUDE.md` and `AGENTS.md` that exist (or a new `AGENTS.md`).
3. Connect the MCP server.
   - Local folder, no account: `claude mcp add notdocs -- notdocs mcp --serve .`
   - Hosted workspace, signed in as the user: `claude mcp add --transport http notdocs https://notdocs.dev/api/mcp`, then have the user run `/mcp` and sign in. The connection reaches every workspace the user can open, with the access they allow.
   - Hosted workspace, unattended (CI, a server): ask the user for the workspace URL, the project and a project token (created in the project's settings, starts with `nd_`). Then `notdocs link --url <url> --project <project>` and `claude mcp add notdocs -- notdocs mcp` with `NOTDOCS_TOKEN` set. Never write the token into a tracked file.
4. Check it: `notdocs status` prints where commands point; `notdocs docs list` lists the documents.

For other MCP clients, the stdio command is `notdocs mcp --serve <folder>`, and the hosted endpoint is streamable HTTP at `https://notdocs.dev/api/mcp`, which signs the user in over OAuth, or takes `Authorization: Bearer <token>` with a project token.

## The content model

- Every document is a `.md` file under the docs root (default `docs/`). Frontmatter `id` is a ULID stamped on first sight; do not change it. `type` picks the schema: `page`, `task`, `decision`, `spec`, `meeting`, `launch`, `runbook`, `postmortem`, `release`, `experiment`, `persona`, `brief`, `slo`, `playbook`, the business and legal types, or custom types from `notdocs.config.json`.
- Start documents from a template: `notdocs templates` lists them; `notdocs docs new docs/specs/search.md --title "Search" --template prd`.
- A fenced block with the language `notdocs` is a query that renders as a board, table or list:

  ````markdown
  ```notdocs
  type: task
  view: board
  groupBy: status
  ```
  ````

- Comments are in `.notdocs/comments/<docId>.yaml`. Use the comment tools or commands rather than editing that file.

## Rules for editing

- Prefer the MCP tools or the CLI to raw file writes when the workspace is hosted: they merge with edits made by people.
- Read before you write. `docs_update` takes the `baseHash` you read; a concurrent edit is merged, and a conflict comes back as a result instead of a write. Report a conflict to the user; do not retry by overwriting.
- When a write's result is lost (a timeout, a dropped connection), retry it with the same `idempotencyKey` you sent the first time; the write is not made twice and its first result comes back. Pass a new key, or none, for a new write.
- To find out what changed, call `changes_since` with your last cursor instead of re-reading every document.
- Link between documents with relative markdown links, and keep frontmatter keys the type's schema knows.
- Check a document with `notdocs validate <ref>` after changing its frontmatter.
- Moving a document (`notdocs docs mv <ref> <newPath>`) keeps its id, history and comments; links written by path in other documents are not rewritten.

## MCP tools you will use most

MCP tool names are the operation names with `_` for `.`.

| Tool | Use |
|---|---|
| `docs_list` | Documents on the branch, filtered by type or path prefix |
| `docs_get` | One document by id or path, with its hash |
| `docs_create` | A new document, from a template or blank |
| `docs_update` | Change text or frontmatter against a `baseHash` |
| `docs_move` | Move or rename, keeping the id |
| `query_run` | Run a query block |
| `search` | Full-text and semantic search |
| `changes_since` | The change feed after a cursor |
| `comments_list`, `comments_add`, `comments_reply`, `comments_resolve` | Comment threads |
| `docs_validate`, `docs_export` | Check a document; export it as Word or HTML |

The server also offers two prompts: planning tasks from a spec, and working through the open comments on a document.