# Markdown and export

One canonical serialization, with block anchors, used by the export, the API, the agent tools and the disk mirror.

## The format

CommonMark, with YAML frontmatter for note metadata and a `{#blockId}` anchor after each block.

```markdown
---
title: Retrieval design
types: [Project]
status: active
---

# Retrieval design {#01JB2K7Q9XN4M8YV3TD0FZ5ERW}

Four arms, fused by weighted RRF. {#01JB2K7Q9XN4M8YV3TD0FZ5ESX}

- lexical {#01JB2K7Q9XN4M8YV3TD0FZ5ETY}
- dense {#01JB2K7Q9XN4M8YV3TD0FZ5EUZ}
```

The anchor is the point. It is what makes a Markdown file a faithful representation of the document rather than a printout of it: the file says which block each paragraph is, so edits made on disk map back exactly.

## The disk mirror

```bash
fp pull ./notes            # write the mirror
$EDITOR ./notes/…
fp push ./notes --dry-run  # see what would change, offline
fp push ./notes            # send it back
```

A push is a diff against known identifiers, never a guess: an anchor whose text changed is an edit to that block; an anchor that vanished is a deletion; a paragraph with no anchor is something new.

File names are built from each note’s title after any credential in it is redacted and any URL neutralized, whoever pulls, so a key pasted into a title never becomes the name of a file on disk. The note’s identifier is part of the name, so two notes with the same title are two files.

> **Important:** `fp pull` refuses to overwrite local edits unless you pass `--force`. Pull into a directory you are not also editing in another window.

## Published notes

Publishing a note makes it readable at `fastpad.ai/n/{id}` with no account. The same URL serves HTML to a browser and Markdown to anything that asks for it.

```bash
curl -H 'Accept: text/markdown' https://www.fastpad.ai/n/01JB2K…
```

Only a signed-in person can publish — no agent credential can, because an agent that could publish could exfiltrate a workspace by making it public and reading it back from outside. An unpublished note, a deleted note and a note that never existed are indistinguishable to an anonymous caller.

## What round-trips

- Headings, paragraphs, lists, tasks, quotes, callouts, code fences, dividers.
- Tables, including cells containing an escaped pipe.
- Links, mentions and the edges behind them.
- Note properties, as frontmatter.
- Block identifiers, on everything.

Attachments are referenced by URL rather than inlined. An export is a directory of text you can read with anything, which is the test this format exists to pass.