diff --git a/README.md b/README.md
index 98f4a4f..33dfd65 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,9 @@ it, as FieldWorks' LCModel does.
 **Status: bootstrap.** This is the native-editor prototype made into a repository. It is not released, the API will
 change, and the list under "Known gaps" is the work still to do.
 
+**Formats:** every format the library reads or writes (FieldWorks Markdown, record files, the clipboard forms) and every finding id is
+documented in [docs/formats](docs/formats/README.md).
+
 ## Projects
 
 | Project | Targets | What it is |
diff --git a/docs/formats/README.md b/docs/formats/README.md
new file mode 100644
index 0000000..2ef9e42
--- /dev/null
+++ b/docs/formats/README.md
@@ -0,0 +1,30 @@
+# Formats
+
+Every format SIL.TextEditing reads or writes. Each page is for a developer who integrates the library and for anyone who edits a file by
+hand. The examples on these pages are copied from the conformance fixtures in `tests/conformance`, and `FormatDocsTests` checks that they
+still match.
+
+| Format | Purpose | File extension or clipboard name | Status | Page |
+|---|---|---|---|---|
+| FieldWorks Markdown | FieldWorks rich text as Markdown, for agents, people and files: a strict profile of Pandoc Markdown. | `*.fw.md`; clipboard id `FieldWorks Markdown` | Shipped (`SIL.TextEditing.Markdown`). Its clipboard form is planned (#168); a host can write its own. | [fieldworks-markdown.md](fieldworks-markdown.md) |
+| Record files | One FieldWorks record, or part of one, as one file: a YAML frame with FieldWorks Markdown values and an optional Markdown body. | `*.fw.md` with a top-level `record:` key | Shipped: reader, writer, schema, findings. Planned: export from liblcm, diffs. | [record-files.md](record-files.md) |
+| Record JSON Schema | A record schema published for editors and checkers, with `contentMediaType` and `x-fieldworks-blocks`. | `<schema id>`, such as `test.schema.json` | Shipped (`RecordSchema.ToJsonSchema`). | [record-files.md](record-files.md#json-schema-export) |
+| Tables | Tables in FieldWorks text: one paragraph per row, written as pipe tables. | part of FieldWorks Markdown | Shipped (tab-separated rows). Planned: real tables with a styled separator. | [tables.md](tables.md) |
+| FieldWorks TsString | FieldWorks' own clipboard form. | clipboard `TsString` | Id shipped. The FieldWorks host writes the form. | [clipboard.md](clipboard.md#fieldworks-tsstring) |
+| Plain text | Text for any program, in NFC. | the system's text format (id `text/plain`) | Shipped. | [clipboard.md](clipboard.md#plain-text) |
+| TsString XML | The XML of one `ITsString`, written by liblcm's serializer. | clipboard `SIL.TextEditing.TsStringXml` | Shipped (`SIL.TextEditing.LCModel`). | [clipboard.md](clipboard.md#tsstring-xml) |
+| Runs dump (`Interchange`) | Every run and property as XML, for tests and debugging; never on a user's clipboard. | clipboard `SIL.TextEditing.Runs.v1` | Shipped, tests and debugging only. | [clipboard.md](clipboard.md#runs-dump-tests-and-debugging) |
+| Word HTML and RTF | Copy to and paste from word processors. | clipboard `HTML Format`, `Rich Text Format` (form names not decided) | Planned (ADR 0031). | [clipboard.md](clipboard.md#planned-word-html-and-rtf) |
+| Findings | Every finding id the readers and the LCModel adapter report, with its meaning and fix. | (not a file format) | Shipped. | [findings.md](findings.md) |
+
+The conformance fixtures themselves are JSON in a documented case format: see `tests/conformance/README.md`.
+
+## Related decisions
+
+- ADR 0011 and ADR 0028: FieldWorks Markdown, a profile of Pandoc Markdown.
+- ADR 0016: the LCModel adapter and the properties liblcm cannot load.
+- ADR 0018: NFD in storage, NFC for other programs.
+- ADR 0029 (amended by ADR 0031): clipboard forms and paste order.
+- ADR 0031: the shared editing and interchange layer, and the planned Word and table work.
+- ADR 0032: record files.
+- ADR 0033: block features.
diff --git a/docs/formats/clipboard.md b/docs/formats/clipboard.md
new file mode 100644
index 0000000..d683c62
--- /dev/null
+++ b/docs/formats/clipboard.md
@@ -0,0 +1,148 @@
+# Clipboard
+
+A field copies a selection in several **clipboard forms** at once and pastes the best one the clipboard holds (ADR 0029). The host
+registers the forms. The field itself depends on neither liblcm nor the Markdown library.
+
+## The forms
+
+| Form | Id | Clipboard format name | Payload | Provided by | Default paste order | "Copy as" | Status |
+|---|---|---|---|---|---|---|---|
+| FieldWorks TsString | `TsString` (`ClipboardForms.TsStringId`) | `TsString` | a host object: FieldWorks' .NET-serialised `TsStringWrapper` | the FieldWorks host | 1st | no | The id ships. The host writes the form and a clipboard backend that can store an object. |
+| FieldWorks Markdown | `FieldWorks Markdown` (`ClipboardForms.FieldWorksMarkdownId`) | chosen by the form | text: [FieldWorks Markdown](fieldworks-markdown.md) with its front matter | the host, around `MarkdownConverter` | 2nd | yes (planned, #168) | Planned, #168. Only the id ships; no form class ships yet. A host can write its own. |
+| Plain text | `text/plain` (`ClipboardForms.PlainTextId`) | the system's text format | text: the paragraphs' text joined with `\n`, in NFC | built into the field | 3rd | always | Shipped. |
+| TsString XML | `SIL.TextEditing.TsStringXml` (`TsStringClipboard.XmlFormatName`) | `SIL.TextEditing.TsStringXml` | text: the XML of one `ITsString` | `TsStringClipboardForm` in `SIL.TextEditing.LCModel` | not in it; the host adds the id | no | Shipped. |
+| Runs dump | `SIL.TextEditing.Runs.v1` | `SIL.TextEditing.Runs.v1` (`Interchange.ClipboardFormat`) | text: `Interchange` XML | `InterchangeClipboardForm` in `SIL.TextEditing` | not in it | yes | Shipped, for tests and debugging only. |
+
+### FieldWorks TsString
+
+FieldWorks puts a .NET-serialised `TsStringWrapper` on the clipboard under `TsString`. That class lives in FieldWorks' own SimpleRootSite
+assembly. This library neither references nor copies it, and nothing here writes under `TsString`. A FieldWorks host registers its own
+form with the id and format name `TsString`:
+
+- its `Write` builds the wrapper from `TsStringClipboard.FragmentToXml`;
+- its `Read` unwraps it and calls `TsStringClipboard.FromXmlToFragment`;
+- its host clipboard backend stores and reads the object, since Avalonia's clipboard cannot.
+
+A TsString copy of several paragraphs joins them with `"; "`. Under the default paste order TsString is read first, so such a copy,
+pasted into another field, arrives as one paragraph, as in FieldWorks. To keep the paragraph breaks, a host registers a FieldWorks Markdown
+form (planned, #168) and puts its id before `TsString` in `PasteOrder`.
+
+### FieldWorks Markdown (planned, #168)
+
+The payload is a whole FieldWorks Markdown text **with its front matter**, so unmarked text never takes its writing system from the
+target project's defaults. Read it with `MarkdownConverter.Parse` and write it with `MarkdownConverter.ToMarkdown`. FieldWorks Markdown
+is a back end first (agents, files, drafting). On the clipboard it is planned as an extra form, not the default (planned, #168).
+
+### Plain text
+
+Every copy puts the plain text on the clipboard: the paragraphs' text joined with `\n`, in NFC (ADR 0018). The field stores NFD; text
+meant for other programs is NFC. The rich forms keep the stored form.
+
+### TsString XML
+
+`TsStringClipboardForm` carries the XML of one `ITsString`, written by liblcm's own `TsStringSerializer`. It is **not** FieldWorks' wire
+format, so it uses its own id and format name, `SIL.TextEditing.TsStringXml`, and can sit beside a host's `TsString` form.
+
+- Copy joins the paragraphs with `WriteParagraphSeparator` (default `"; "`, as FieldWorks does).
+- Paste gives one paragraph, as FieldWorks does, unless `PasteParagraphSeparator` is set; then it splits there.
+- A writing system the host's handles do not know keeps its id during the read, so the paste rule below can map it.
+- A property liblcm cannot load back is left out and reported to `OnDropped` (see [Findings](findings.md#lcmodel-adapter)).
+- The id is not in the default paste order. A host that wants it adds it.
+
+### Runs dump (tests and debugging)
+
+`Interchange.ToXml` writes every run, writing system and property, with nothing lost. ADR 0029 retired it from the user's clipboard;
+`InterchangeClipboardForm` exists so that tests and the playground can carry formatting without liblcm or the Markdown library. Its
+shape, from `src/SIL.TextEditing/Interchange.cs`:
+
+| Element | Attributes |
+|---|---|
+| `Runs` | the root |
+| `Para` | `style`, `rtl` (`1` or `0`), `defws`, then one attribute per property: `i_<number>="<variation>:<value>"` for an integer property, `s_<number>="<text>"` for a string property |
+| `Run` | `ws`, `objdata` when the run has object data, and the property attributes; the text is the content |
+
+A backslash, a control character, a lone surrogate and U+FFFC are escaped as `\\` and `\uXXXX` in text and string values, so any XML
+reader gets the exact UTF-16 back. `Interchange.Json` is a JSON dump of a document for exact comparison in tests; it is not a clipboard
+form.
+
+## Copy
+
+- `RichTextField.CopyAsync` asks every registered form for its payload and puts them all on the clipboard with the plain text.
+- A form that returns null, returns an empty string or throws is left out. The others still go.
+- The backend reports the format names it could not store. The field raises `ClipboardFormsNotStored` with them.
+
+## Paste
+
+`RichTextField.PasteAsync` tries the ids of `ClipboardForms.PasteOrder` in turn and uses the first form that the clipboard holds and that
+reads.
+
+- The default order is FieldWorks' own: `TsString`, `FieldWorks Markdown`, `text/plain`.
+- The host may replace or edit the list. An id with no registered form is skipped. A form whose id is not in the list is never read.
+- A payload a form cannot read (null, or an exception) is skipped, so paste falls through to the next form.
+- The editor normalises the pasted text to the form the host stores (`Document.Normalization`; NFD for FieldWorks).
+- A block the field does not allow is flattened, and the field raises `BlocksFlattened` (ADR 0033).
+
+## The writing-system rule
+
+Text in a writing system the target project lacks takes the writing system of the selection it replaces, as FieldWorks does
+(`ClipboardWritingSystems.MapMissing`).
+
+- The field asks `RichTextField.KnowsWritingSystem`. By default that is its `WritingSystems` registry, and an empty registry accepts every
+  writing system.
+- After a paste that mapped something, the field raises `WritingSystemsMapped` with the missing ids and the target, so the host can show a
+  notice.
+- A run with no writing-system id takes the target's too, but is not listed as missing.
+- The rule runs for every rich form. Plain text has no writing system; it is pasted as typed text is.
+
+## Copy as
+
+`RichTextField.CopyAsAsync(formId)` puts one form on the clipboard as text: the plain text (`text/plain`), or any registered form
+whose payload is a string, such as FieldWorks Markdown (planned, #168). It returns false for an unknown id, for a form whose payload is
+not a string, and for a form with nothing to say. `OffersCopyAs` does not limit `CopyAsAsync`; it only decides which forms
+`ClipboardForms.CopyAsForms` lists for a menu.
+
+## Backends
+
+The field reads and writes the clipboard only through `IClipboardBackend` (`RichTextField.ClipboardBackend`):
+
+| Member | Does |
+|---|---|
+| `SetAsync(plainText, forms)` | Replaces the clipboard with the plain text and the named payloads. Returns the names it could not store. |
+| `GetAsync(formatName, kind)` | The payload under a name, read as the form's `ClipboardPayloadKind`, or null. Must not throw on data it does not understand. |
+| `GetTextAsync()` | The plain text, or null. |
+
+- Payloads pass through untouched. A form says what it holds (`PayloadKind`): `Text` (a string), `Bytes` (a `byte[]`) or `Object` (a
+  host object). The backend reads a format back as that kind and never guesses text from bytes.
+- The default backend is Avalonia's clipboard of the field's window (`AvaloniaClipboardBackend`). It stores strings and `byte[]`s. It
+  cannot store a host object and reports it as not stored.
+- FieldWorks' WinForms host plugs in its own backend, so it can keep the clipboard itself and store the `TsStringWrapper` object.
+
+## Planned: Word HTML and RTF
+
+> **Planned. Nothing in this section is built.** It says what the owner has decided, so that integrators know what is coming.
+
+The owner decided on 2026-11-05 (recorded as planned additions in ADR 0031):
+
+- Copy writes Word-compatible HTML and RTF. This reverses ADR 0029's "no HTML or RTF". TsString stays first on paste between FieldWorks
+  fields.
+- Paste reads HTML only. Whether to read RTF is decided after testing with Word.
+- Paste from Word keeps meaning (emphasis, links, styles, language, writing system) and drops fonts, sizes and colours. A host setting
+  allows full formatting.
+- Writing systems travel as character styles named `<Style>[lang=<ws>]`, as FieldWorks' Word export does. A host switch turns this off.
+- Host callbacks for footnotes and pictures are defined in the first version's API and built right after it.
+- The paste order becomes TsString, FieldWorks Markdown, HTML, RTF, plain text.
+- There is no "Copy as HTML source".
+- HTML is read with the AngleSharp package, if it passes the AOT check.
+- One new project, `SIL.TextEditing.WordInterchange`, holds the importer and the exporter.
+
+Not decided yet: the forms' ids and format names. The Windows clipboard names are `HTML Format` and `Rich Text Format`. Both forms
+would carry bytes, so neither could be used with "Copy as". `IClipboardForm` and `IClipboardBackend` need no change.
+
+## Planned: tables on the clipboard
+
+> **Planned.** See [Tables](tables.md) for the storage and editing design.
+
+- On the Markdown side a table stays a standard pipe table.
+- Tab-separated text pasted at a paragraph boundary becomes a table, and "Paste as table" is offered too.
+- Today a paste into a field that does not allow tables already flattens a table to one plain paragraph per row, cells joined by
+  ` | ` (ADR 0033).
diff --git a/docs/formats/fieldworks-markdown.md b/docs/formats/fieldworks-markdown.md
new file mode 100644
index 0000000..db4d395
--- /dev/null
+++ b/docs/formats/fieldworks-markdown.md
@@ -0,0 +1,562 @@
+# FieldWorks Markdown
+
+FieldWorks Markdown is the Markdown form of FieldWorks rich text. It is a strict profile of Pandoc Markdown: every file is valid Pandoc
+Markdown, and Pandoc reads it to the same structure as this library (ADR 0028). It carries everything a FieldWorks paragraph holds:
+writing systems, styles, every text property, links and pictures.
+
+| | |
+|---|---|
+| File name | `*.fw.md` (`MarkdownFrontMatter.FileExtension`). Only a hint: the front matter decides. |
+| Clipboard id | `FieldWorks Markdown` (`ClipboardForms.FieldWorksMarkdownId`). The form itself is planned (#168); see [Clipboard](clipboard.md). |
+| Version | `fwmd: 1` (`MarkdownFrontMatter.CurrentVersion`). |
+| API | `MarkdownConverter.ToMarkdown`, `Parse`, `Canonicalize`, `ToInlineMarkdown`, `ParseInline`, `AreEquivalent` in `SIL.TextEditing.Markdown`. |
+| Defined by | The conformance fixtures in `tests/conformance` (their README explains the case format) and ADRs 0011, 0018, 0028 and 0029. The parser does not define the format. |
+
+**Read lenient, write strict.** The reader takes any spelling Pandoc reads to the same structure. The writer writes one canonical spelling
+and reads every paragraph back to check it. A non-canonical spelling is not an error. `Canonicalize` gives the canonical form of a text.
+
+**The examples** on this page are copied from the fixtures; each names its file and case. A test (`FormatDocsTests`) checks that they
+still match. A case with no front matter of its own is read after the fixtures' standard front matter: `analysis` is `en` and
+`vernacular` is `ceb`. So unmarked text is English and `.v` is Cebuano.
+
+## A whole file
+
+A file is YAML front matter, a blank line, then the paragraphs. Each paragraph is one line. Blocks are separated by one blank line. Line
+ends are `\n`.
+
+<!-- fixture: 06-front-matter.json | the writing systems the text uses are listed with language, direction and font, the defaults first | canonical -->
+```markdown
+---
+fwmd: 1
+analysis: "en"
+vernacular: "ceb"
+writingSystems:
+  en:
+    lang: "en"
+    dir: "ltr"
+    font: "Charis SIL"
+  ceb:
+    lang: "ceb"
+    dir: "ltr"
+    font: "Charis SIL"
+  ar:
+    lang: "ar"
+    dir: "rtl"
+    font: "Scheherazade New"
+  ceb-x-old:
+    lang: "ceb"
+    dir: "ltr"
+    font: "Doulos SIL"
+---
+
+[a]{ws=ar}[b]{ws=ceb-x-old}c
+```
+
+## Front matter
+
+| Key | Value |
+|---|---|
+| `fwmd` | The format version, a whole number. `1` today. A newer version is refused with `fwmd.version.unsupported`, and nothing is read. |
+| `analysis` | The writing system of unmarked text. |
+| `vernacular` | The writing system `.v` stands for. |
+| `writingSystems` | Each writing system the text uses, the two defaults first: its id as the key, then `lang` (language tag), `dir` (`ltr` or `rtl`) and `font`. |
+
+- The writer generates it (`MarkdownOptions.WriteFrontMatter`, default on). People do not maintain it by hand.
+- Values are written double-quoted. The reader also takes bare and single-quoted values (`06-front-matter.json`, "values may be bare or
+  single-quoted and are written double-quoted").
+- The file's `analysis` and `vernacular` win over the host's defaults. The project's own writing-system definitions win over `writingSystems`.
+- Front matter with no `fwmd` key is some other YAML and is ignored. Text with no front matter takes the host's defaults
+  (`MarkdownOptions.WritingSystems`).
+- A top-level `record:` key makes the file a [record file](record-files.md). `Parse` refuses it with `fwmd.record.record-file`.
+- A byte order mark at the start is ignored.
+- Problems in the front matter are `fwmd.syntax.malformed-attribute`: `fwmd` that is not a number, an empty or list default, a tab in the
+  indentation (Pandoc refuses it).
+
+## Runs and writing systems
+
+A run is text in one writing system with one set of properties. Unmarked text is the `analysis` writing system. A span `[...]{...}`
+gives its text other attributes.
+
+<!-- fixture: 01-blocks.json | vernacular span in an analysis paragraph | markdown -->
+```markdown
+The prefix [mang-]{.v}.
+```
+
+- `.v` means the `vernacular` writing system. `ws=<id>` names any other writing system of the project, such as `ws=ceb-x-old`.
+- `.v` and `ws=` together are `fwmd.syntax.duplicate-attribute`.
+- The writer writes `.v` for the default vernacular, `ws=` for any other non-analysis writing system, and nothing for the analysis.
+- An inner span overrides an outer one. The result is always flat runs (`02-attributes.json`, "an inner span overrides an outer one, and
+  the result is flat runs").
+- Bold and italic set to `on` are written with stars when the run starts and ends with a letter or digit and has no other attribute.
+  Otherwise they are attributes:
+
+<!-- fixture: 07-star-rule.json | a run with a leading or trailing space or punctuation uses the attribute form | canonical -->
+```markdown
+[&#x20;x]{bold=on}; [y.]{bold=on} [(z)]{italic=on}
+```
+
+- `^x^` and `~x~` are read as superscript and subscript, and written as `[x]{superscript=super}` and `[x]{superscript=sub}`.
+
+## Attributes
+
+An attribute block follows `]` or `)` with no space. It holds classes and `key=value` pairs, separated by one space.
+
+```text
+block  = "{" item { " " item } "}"      ; "{}" is an error
+item   = class | pair
+class  = "." ALPHA { ALPHA | DIGIT | "-" | "_" }
+pair   = key "=" value
+key    = ALPHA { ALPHA | DIGIT | "-" }
+value  = bare | quoted
+bare   = 1*( ALPHA | DIGIT | "-" | "_" | "." | ":" | "#" | "/" )
+quoted = DQUOTE { char | "\" DQUOTE | "\\" } DQUOTE
+```
+
+(The grammar is quoted from `AttributeScanner` in `src/SIL.TextEditing.Markdown/Notation/AttributeBlock.cs`.)
+
+### Classes
+
+| Class | Meaning |
+|---|---|
+| `.v` | The run is in the default vernacular writing system. |
+| `.name` | A link whose text is the target's current name. |
+| `.example` | A link to a text segment: a glossed example. |
+| `.broken` | A link whose target was deleted. |
+| `.empty` | An empty paragraph's marker, `[]{.empty}`. |
+| `.nul` | A NUL character, `[]{.nul}`. CommonMark cannot carry it. |
+| `.surrogate` | An unpaired surrogate, `[]{.surrogate x=D800}`. CommonMark cannot carry it. |
+| `.nostyle` | A link run with no character style. |
+
+The writer writes classes in this order: `.v .name .example .broken .empty .nul .surrogate .nostyle`.
+
+### Canonical order
+
+The writer writes, in this order: the classes; `ws=`; `custom-style=`; a link's `guid=`, `tool=` and `url=`; the named properties in
+alphabetical order (ignoring case); `pN` by number; `sN` and `sNx` by number. The reader takes any order.
+
+<!-- fixture: 02-attributes.json | attributes are read in any order and written in canonical order | markdown -->
+```markdown
+[x]{italic=on bold=off ws=ceb-x-old}
+```
+
+is written
+
+<!-- fixture: 02-attributes.json | attributes are read in any order and written in canonical order | canonical -->
+```markdown
+[x]{ws=ceb-x-old bold=off italic=on}
+```
+
+### Property keys
+
+Every text property has a key, so nothing is lost. A property with a FieldWorks number and no named key is `pN` (an integer) or `sN`
+(a string).
+
+| Key | Number | Values |
+|---|---|---|
+| `italic`, `bold` | 2, 3 | `off`, `on`, `invert` |
+| `superscript` | 4 | `off`, `super`, `sub` |
+| `underline` | 5 | `none`, `dotted`, `dashed`, `single`, `double`, `strikethrough`, `squiggle` |
+| `align` | 17 | `leading`, `left`, `center`, `right`, `trailing`, `justify` |
+| `spellcheck` | 26 | `normal`, `donotcheck`, `forcecheck` |
+| `editable` | 155 | `no`, `yes`, `semi` |
+| `fontsize`, `offset` | 6, 7 | millipoints; add `fontsizeUnit=rel` (or `offsetUnit=rel`) for a relative value |
+| the measures in the first table below | see below | millipoints, with a `...Unit` key as above. `marginTop` is read for `MarginTop`. |
+| `lineHeight` | 24 | millipoints, with `lineHeightUnit=rel` and `lineHeightType=exact` (default `atLeast`) |
+| the colours in the first table below | see below | `#rrggbb`, `transparent` or a colour name (`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`) |
+| the whole numbers in the first table below | see below | a whole number |
+| the strings in the second table below | see below | text |
+| `custom-style` | string 133 | a character style on a span, a paragraph style on a div |
+| `pN` | integer N | `value:variant`, such as `p150=1:default`. The variant is `default`, `mpt`, `rel`, `enum`, `ninch` or a number. |
+| `sN` | string N | text |
+| `sNx` | string N | the text as hex: four uppercase digits per UTF-16 code unit |
+
+Integer properties:
+
+| Key | Number |
+|---|---|
+| `firstIndent` | 18 |
+| `leadingIndent` | 19 |
+| `trailingIndent` | 20 |
+| `spaceBefore` | 21 |
+| `spaceAfter` | 22 |
+| `tabDef` | 23 |
+| `MarginTop` | 50 |
+| `padLeading` | 134 |
+| `padTrailing` | 135 |
+| `padTop` | 136 |
+| `padBottom` | 137 |
+| `borderTop` | 138 |
+| `borderBottom` | 139 |
+| `borderLeading` | 140 |
+| `borderTrailing` | 141 |
+| `forecolor` | 8 |
+| `backcolor` | 9 |
+| `undercolor` | 10 |
+| `paracolor` | 25 |
+| `borderColor` | 142 |
+| `rightToLeft` | 128 |
+| `directionDepth` | 129 |
+| `bulNumScheme` | 143 |
+| `bulNumStartAt` | 144 |
+| `keepWithNext` | 148 |
+| `keepTogether` | 149 |
+| `widowOrphan` | 162 |
+
+String properties:
+
+| Key | Number |
+|---|---|
+| `fontFamily` | 1 |
+| `tabList` | 4 |
+| `tags` | 5 |
+| `fontVariations` | 130 |
+| `bulNumTxtBef` | 145 |
+| `bulNumTxtAft` | 146 |
+
+- A named key is used only when it spells the value exactly. Otherwise the writer uses `pN`. A relative font size is written
+  `fontsize=150 fontsizeUnit=rel`; `p6=150:rel` is read too.
+- A string with a control character or a lone surrogate is written as `sNx`, whatever its key:
+
+<!-- fixture: 02-attributes.json | a string with a control character is written as hex, four uppercase digits for each UTF-16 code unit | canonical -->
+```markdown
+[&#xFFFC;]{s6x=000500610062}
+```
+
+- A number FieldWorks does not define is kept, with the warning `fwmd.prop.unknown-number`.
+- A paragraph's direction (`Paragraph.Rtl`) is `rightToLeft=1` on its div.
+
+### Quoting
+
+A value is bare when it holds only ASCII letters (`A`–`Z`, `a`–`z`), digits and `- _ . : # /`. Any other letter, such as `É`, needs quotes. Any other value is in double quotes. Inside quotes, `\"` and `\\`
+are the only escapes. A `}`, a space or an `=` inside quotes is text.
+
+<!-- fixture: 02-attributes.json | a quoted value escapes only a double quote and a backslash | markdown -->
+```markdown
+[x]{fontFamily="a\"b\\c d}e=f'g"}
+```
+
+- An ampersand is written `&amp;` only where it would read as a character reference.
+- A control character in a value that is not a string property (such as a style name) is a character reference: `&#x9;`.
+- A value that starts with white space has that character written as a reference (`&#x20;`), which Pandoc needs.
+- The reader also takes single quotes, extra spaces and character references, as Pandoc does. The writer never writes them.
+- Attribute values are never normalised.
+
+## Styles
+
+`custom-style=` names a style, as Pandoc's Word writer does. On a span it is a character style. On a div it is a paragraph style.
+
+- The writer leaves out `custom-style=` for the `Hyperlink` style on a link, because a link implies it. `.nostyle` marks a link with no
+  character style.
+- The paragraph styles of the block syntax default to the names a new FieldWorks project has (`MarkdownStyleNames`):
+
+| Markdown | Paragraph style |
+|---|---|
+| a plain paragraph | `Normal` |
+| `#`, `##`, `###` | `Heading 1`, `Heading 2`, `Heading 3` |
+| `- ` | `Bulleted List` |
+| `1. ` | `Numbered List`. The number is not stored; the writer numbers from 1. |
+| `> ` | `Block Quote` |
+| a pipe table | the host's table header and row styles. They have no default. |
+| a div | the style in its `custom-style=` |
+
+- A heading deeper than `###` is `fwmd.heading.too-deep`.
+- With `MarkdownOptions.Styles` set, a style the project lacks is `fwmd.style.unknown`.
+
+<!-- fixture: 04-structure.json | adjacent list paragraphs are one tight list each | canonical -->
+```markdown
+- a
+- b
+
+1. c
+2. d
+```
+
+## Empty and special paragraphs
+
+An empty paragraph has no run, so its marker names its writing system:
+
+<!-- fixture: 04-structure.json | empty paragraphs name their writing system in the marker | canonical -->
+```markdown
+[]{.empty}
+
+[]{.v .empty}
+
+[]{.empty ws=ceb-x-old}
+
+[]{.empty ws=ar}
+```
+
+- A styled empty paragraph is a div around the marker (`04-structure.json`, "an empty paragraph with a style is a div around the marker").
+- The marker must be the whole paragraph. `[]{.empty} more` is `fwmd.syntax.unsupported-markup`.
+- `[]{.nul}` is a NUL and `[]{.surrogate x=D800}` an unpaired surrogate. They are the two characters CommonMark cannot carry.
+- An embedded object with data the notation has no form for is a span over U+FFFC with the data in `s6x` (see above).
+
+## Divs
+
+A paragraph with another style, or with paragraph properties, is in a Pandoc div. One div holds a maximal run of adjacent paragraphs
+with the same style and properties. Paragraphs inside are separated by blank lines.
+
+<!-- fixture: 04-structure.json | one div holds a maximal run of paragraphs with the same style and properties, and two runs make two divs | canonical -->
+```markdown
+::: {custom-style=Example}
+a
+
+b
+:::
+
+::: {custom-style=Example spaceBefore=6000}
+c
+:::
+```
+
+- A `Normal` paragraph with properties is a div with no `custom-style=`. A heading with properties is a div with the heading style.
+- Inside a styled div, block markers are text and must be escaped (`\#`). An unescaped one is `fwmd.syntax.unsupported-markup`, with
+  the escape as the fix.
+- A div inside a div has no counterpart: `fwmd.syntax.unsupported-markup`.
+- A `:::` line straight after a paragraph line is text in Pandoc. The fix adds a blank line before it.
+- A soft line break in a paragraph is one space.
+
+## Tables
+
+A pipe table is one paragraph per row: the header row in the host's header style, the body rows in its row style, and a tab between
+cells. [Tables](tables.md) has the details and the planned design.
+
+<!-- fixture: 04-structure.json | a table is a header row, a delimiter row and body rows, one paragraph per row with tab-separated cells | markdown -->
+```markdown
+| Form | Gloss |
+|---|---|
+| [palit]{.v} | change |
+| [mamalit]{.v custom-style="Emphasized Text"} | buy \| sell |
+```
+
+## Links
+
+Every reference to a FieldWorks object is a Markdown link to the object's **project path**, with `guid=`. The GUID is the identity. The
+path finds the object and is refreshed when the text is written again.
+
+<!-- fixture: 05-links.json | a link is a path with the GUID, the name form marks text that follows the target's name | markdown -->
+```markdown
+See [palit](/lexicon/palit(2)){.name guid=7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d}.
+```
+
+`.name` says that the link text is the target's current name.
+
+### The five forms
+
+The reader takes all five and converts between them without loss. `MarkdownOptions.LinkForm` picks the one the writer writes. Here is the
+same link in each form.
+
+| Form | `MarkdownLinkForm` | Use |
+|---|---|---|
+| A | `RootPath` (default) | Agents, source mode, the clipboard. |
+| B | `FileRelative` | A full export to files. Needs `LinkBase`, the path of the file being written. |
+| C | `SilfwUrl` | A back-link that opens FieldWorks. |
+| D | `MotifUrl` | A back-link that opens Motif. Needs `ProjectName`. |
+| E | `ObjectAlias` | `/objects/<guid>`. Also used for any target with no path. |
+
+<!-- fixture: 05-links.json | the same link written in each of the five forms: A | canonical -->
+```markdown
+[palit](/lexicon/palit(2)){.name guid=7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d}
+```
+
+<!-- fixture: 05-links.json | the same link written in each of the five forms: B | canonical -->
+```markdown
+[palit](../../lexicon/palit(2).fw.md){.name guid=7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d}
+```
+
+<!-- fixture: 05-links.json | the same link written in each of the five forms: C | canonical -->
+```markdown
+[palit](silfw://localhost/link?database%3dthis%24%26tool%3dlexiconEdit%26guid%3d7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d%26tag%3d){.name}
+```
+
+<!-- fixture: 05-links.json | the same link written in each of the five forms: D | canonical -->
+```markdown
+[palit](motif://projects/Sena3/lexicon/palit(2)?guid=7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d){.name}
+```
+
+<!-- fixture: 05-links.json | the same link written in each of the five forms: E | canonical -->
+```markdown
+[palit](/objects/7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d){.name}
+```
+
+Form B was written with `LinkBase` `/lists/GDR/GDR-47.fw.md`, and form D with `ProjectName` `Sena3`.
+
+### Project paths
+
+- The top folders are `lexicon`, `texts`, `grammar`, `notebook`, `lists`, `reversals`, `objects` and `files` (`ProjectPath.TopFolders`).
+  A path under any other folder, with no GUID, is an external address.
+- A homograph number is in parentheses: `palit(2)`. The reader also takes `palit₂`.
+- Siblings that share a name get eight GUID digits: `Epenthesis(77e41a02)`.
+- A path is written in NFC and compared under canonical equivalence, case-sensitively.
+- A `/`, `%`, `?`, `#` or `\` in a name, an unbalanced parenthesis, and a name that itself ends in a number in parentheses are
+  percent-encoded. A destination with a space is in angle brackets:
+
+<!-- fixture: 09-paths.json | balanced parentheses stay raw and a space puts the destination in angle brackets | canonical -->
+```markdown
+[Noun (common)](</lexicon/Noun (common)>){.name guid=00000009-0000-4000-8000-000000000009}
+```
+
+- A fragment names a field and a writing system: `/lexicon/palit(2)#definition.en`. It is reserved: read, kept and written back, not
+  resolved.
+- The host resolves paths through `IProjectPathResolver` (`MarkdownOptions.Paths`). With none, paths and `guid=` are kept as written.
+
+### Stored URLs and tools
+
+- FieldWorks stores a link as a `silfw://` URL. When the stored URL is not the one the writer would rebuild (extra parameters, another
+  project), it is kept in `url=`:
+
+<!-- fixture: 05-links.json | a stored URL that FieldWorks wrote with extra parameters survives as url= | canonical -->
+```markdown
+[palit](/lexicon/palit(2)){.name guid=7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d url="silfw://localhost/link?database%3dthis%24%26tool%3dlexiconEdit%26guid%3d7d2c9a10-3e4f-4a5b-8c6d-7e8f9a0b1c2d%26server%3dx%26tag%3d"}
+```
+
+- `tool=` names the FLEx tool when the path does not give it.
+- An unknown GUID makes the link broken (`fwmd.link.broken`) unless `MarkdownOptions.UnknownGuids` is `RebindByPath`, which an
+  interactive paste uses (`fwmd.link.rebound`).
+
+### External links
+
+An external link is a plain Markdown link and takes the same attributes as any run.
+
+<!-- fixture: 05-links.json | an external link takes the same attributes as any run, and .nostyle means no character style | canonical -->
+```markdown
+[a](https://x.org/){.v bold=on}[b](https://x.org/){.nostyle}[c](https://x.org/){custom-style="Emphasized Text"}
+```
+
+An address that cannot stand as a destination is written `[x](<>){url="..."}`.
+
+## Pictures and glossed examples
+
+A picture is an image link to its file path, with its GUID. The alt text is the caption.
+
+<!-- fixture: 05-links.json | ok: fwmd.picture.unknown a picture the project holds | markdown -->
+```markdown
+![A hut](/files/pictures/hut.jpg){guid=1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9}
+```
+
+A glossed example is a link to a text segment, with the class `.example`. The full interlinear is not in the Markdown.
+
+<!-- fixture: 05-links.json | a glossed example is a link to a text segment with the class example | markdown -->
+```markdown
+[(1)](/texts/Kuwento/3.2){.example guid=5b6c0e2a-1d3f-4c8e-9a71-0f2b3c4d5e6f}
+```
+
+## Escapes
+
+Grammar prose is full of brackets and symbols. Most of them need no escape:
+
+<!-- fixture: 03-escapes.json | no escape is needed for brackets, braces, slashes, arrows, underscores inside words, hyphens, a single tilde or an address | canonical -->
+```markdown
+[ng] [+nasal] {a,b} /a/ C -> [+nasal] a_b -um- ~ -in- x@y.org
+```
+
+The writer escapes a character only where Pandoc would read it as markup:
+
+| Character | Escaped |
+|---|---|
+| `\`, `` ` ``, `*` | always |
+| `_` | where it could open or close emphasis |
+| `<` | where it could start a tag, an autolink or a comment |
+| `&` | where it could read as a character reference |
+| `$`, `^`, `~` | where another one follows in the paragraph; `^` also before `[` |
+| `@` | unless a letter or digit comes before it (a citation) |
+| `[`, `]` | a literal pair before `(`, `[` or `{`; an unbalanced bracket in a span; a pair nested deeper than eight |
+| `!` | before `[` |
+| `\|` | in a table row, every `\|` that is not a cell separator |
+| a block marker at the start of a paragraph | `#`, `>`, `+`, `-`, `\|`, `:`, `~`, `%` (first line), a list number's `.` or `)`, `Table:` |
+
+<!-- fixture: 03-escapes.json | a block marker at the start of a paragraph is escaped | canonical -->
+```markdown
+\# not a heading
+
+\> not a quote
+
+\+ not a list
+
+\- not a list
+
+-not a list either
+
+\--
+
+\| not a table
+```
+
+White space and line breaks:
+
+- Leading, trailing and repeated spaces are `&#x20;`. A no-break space, a tab and a form feed outside a table are numeric references.
+- U+FFFC outside an object run is `&#xFFFC;`.
+- A hard line break (U+2028) is `\` at the end of the line. At the start or end of a paragraph, or next to another, it is `&#x2028;`.
+- A literal backslash at the end of a paragraph is `\\`.
+- On read, a raw tab is a space (as in Pandoc), two trailing spaces are a hard line break, and an escape that is not needed is fine.
+
+## Unicode: NFD and NFC
+
+- `Parse` and `ParseInline` return run text in NFD, the form FieldWorks stores (ADR 0018). `MarkdownOptions.NormalizeText = false` keeps
+  the text as written.
+- Attribute values (`s6` object data, `url=`, `guid=`, `sN`, `pN`) are never normalised.
+- `ToMarkdown` writes the text as stored. `AreEquivalent` treats two texts as equal when they are equal in NFD.
+- Link paths are written in NFC.
+- Finding offsets, lines and columns refer to the text as written (`Source`).
+- Plain text the field puts on the clipboard is NFC (see [Clipboard](clipboard.md)).
+
+## Fields of one paragraph
+
+A multi-string field (an abstract, a gloss) holds one paragraph. `ToInlineMarkdown` writes it with no front matter, and `ParseInline`
+reads it. Block syntax there (a heading, a list, a div, a blank line) is `fwmd.field.block-syntax`. A line break is `\` at the end of a
+line.
+
+## Limits
+
+| Limit | What happens |
+|---|---|
+| Headings | Three levels. A deeper one is `fwmd.heading.too-deep`. |
+| Nesting | Markdig's depth limit. Deeper text is one `fwmd.syntax.too-deep` finding, and its lines are kept as plain text. |
+| Table size | Markdig reads a pipe table only while rows × (columns + 1) stays under about 10,200. A bigger table is `fwmd.syntax.too-deep` on read, and divs on write. |
+| Homograph numbers | 1 to 999. |
+| Slow inputs | A few inputs are slow in Markdig itself: tens of thousands of `[a](`, a table of about 4,000 rows, a list nested a thousand deep. A host that reads untrusted text should bound its size. |
+| Writer | `ToMarkdown` throws `MarkdownWriteException` when a paragraph cannot be written so that it reads back the same. For text this should not happen; the usual cause is a host's `IObjectMapper` that does not invert itself. |
+
+## Unsupported Pandoc constructs
+
+Pandoc reads these, and FieldWorks text has no counterpart. Each is `fwmd.syntax.unsupported-markup`. Where an escape keeps the text,
+the finding's fix is that escape.
+
+- Raw HTML, code spans, thematic breaks (`***`) and link reference definitions.
+- Nested lists, and a div inside a div.
+- Math (`$x$`), citations (`@doe`), inline notes (`^[note]`), strikeout (`~~x~~`) and an empty subscript (`~~`).
+- Heading attributes (`# Title {#id}`).
+- Fancy list markers (`a.`, `(1)`, `II.`, `A.` followed by two spaces, `(@)`, `#.`), line blocks (`| x`), grid tables, definition lines
+  (`: meaning`, `~ meaning` after a term) and a `Table:` caption next to a table.
+- A pipe table when the host names no table styles.
+
+Pandoc's own rules decide, not a broader escape rule. Prose such as `M. Dixon`, `A. Consonants`, `I. Introduction`, `Table: the forms
+are given in Appendix B.` or `#palit#` is plain text in both and is never reported (`12-pandoc-prose.json`). A wrapped line that starts
+with `#`, `-`, `+`, `>` or `1.` stays in its paragraph, as in Pandoc.
+
+## Relation to Pandoc
+
+FieldWorks Markdown is read as Pandoc reads it with these extensions off:
+
+```text
+pandoc -f markdown-smart-implicit_figures-implicit_header_references-task_lists
+```
+
+- `PandocAgreementTests` reads every fixture, its canonical form and generated documents with that reader (`-t json`), and requires the
+  same paragraphs. CI pins the Pandoc version. Locally the test skips when Pandoc is missing.
+- Pandoc constructs the format uses: YAML metadata, bracketed spans with attributes, links and images with attributes, fenced divs,
+  `custom-style`, headings, lists, block quotes and pipe tables. Pandoc's `^x^` and `~x~` are read, not written.
+- The library itself reads with Markdig.Signed 0.37.0 and a notation extension of its own. It moves to Markdig 1.x only if every
+  fixture passes unchanged (ADR 0028).
+
+## For integrators
+
+- Everything project-aware reaches the converter through `MarkdownOptions`: `WritingSystems` (`IWritingSystemMapper`, optionally
+  `IKnownWritingSystems`, `IWritingSystemChecker`, `IWritingSystemDetails`), `StyleNames` and `Styles` (`IStyleCatalog`, optionally
+  `IKnownStyles`, `IStyleChecker`), `Objects` (`IObjectMapper`, optionally `IObjectResolver`) and `Paths` (`IProjectPathResolver`). All are
+  optional. The defaults need no project.
+- `MarkdownParseResult.Objects` lists the links and pictures the parser built, with their ranges. `CreateDiagnostic` makes a placed
+  finding for a host check.
+- Every finding id is in [Findings](findings.md).
+- A net48 host needs binding redirects for Markdig.Signed's dependencies (System.Memory, System.Buffers,
+  System.Runtime.CompilerServices.Unsafe). The test project's `app.config` is the model.
diff --git a/docs/formats/findings.md b/docs/formats/findings.md
new file mode 100644
index 0000000..c1a9162
--- /dev/null
+++ b/docs/formats/findings.md
@@ -0,0 +1,168 @@
+# Findings
+
+A **finding** is what a reader reports about its input: a stable id, a severity, a place and, where one exists, the one exact fix.
+This page lists every id the library can report. `FormatDocsTests` checks both ways: every id in the source is listed here, and every id listed in a table here is in the source.
+
+- [FieldWorks Markdown](fieldworks-markdown.md) findings are `fwmd.*` and come from `MarkdownConverter.Parse` and `ParseInline`.
+- [Record file](record-files.md) findings are `fwmd.yaml.*` (the YAML of the frame) and `fwmd.record.*` (what the frame says against the
+  schema). `RecordFileReader` also reports the FieldWorks Markdown ids for text inside rich values and the body, placed in the file.
+- The LCModel adapter's ids are `textediting.lcm.*`. They are not `MarkdownDiagnostic`s; see [the last section](#lcmodel-adapter).
+
+Every fixture case cited below is in `tests/conformance` (Markdown) or `tests/conformance/records` (record files).
+
+## How a finding looks
+
+| Member | Meaning |
+|---|---|
+| `Id` | The id, as listed below. |
+| `Severity` | `Error`, `Warning` or `Suggestion`. This page calls a suggestion **information**: the text is read as it means, and the writer spells it canonically next time. |
+| `Line`, `Column`, `EndLine`, `EndColumn` | 1-based. Columns count UTF-16 code units. The end is exclusive. |
+| `Start`, `End` | UTF-16 offsets in `Source`, the text as written. |
+| `Observed` | The text the finding is about. |
+| `Replacement` | The one exact replacement of `Observed` that fixes it, or null when the intent is not clear. |
+| `Choices` | The candidates, when there is no single safe fix (an ambiguous link, an unknown writing system). |
+| `Nearest` | Names close to the one written (a style, a writing system, a field). |
+
+A text with an error is still read as far as it can be. `HasErrors` says whether any finding is an error.
+
+**Hosts add and change findings.** The ids below are the library's. A host's checker can give its own id and severity:
+`IWritingSystemChecker.CheckWritingSystem`, `IStyleChecker.CheckStyle` and `IObjectResolver` return a `MarkdownProblem` with an optional
+id and severity, and an `INotationChecker` returns `LanguageDiagnostic`s whose `Code` is the id. `MarkdownParseResult.CreateDiagnostic`
+makes a placed finding for any other check a host runs.
+
+## FieldWorks Markdown: syntax
+
+| Id | Severity | Meaning | Usual fix |
+|---|---|---|---|
+| `fwmd.syntax.unclosed-mark` | error | An attribute block has no closing `}`, or a div has no closing `:::`. Fixtures: `02-attributes.json` "a block with no closing brace is an error with the closing brace as the fix"; `04-structure.json` "a div that is never closed is an error". | Add the `}` (the finding's fix) or the closing `:::` line. |
+| `fwmd.syntax.unknown-attribute` | error | A key or class the notation does not have (`{wss=ceb}`, `{.vern}`), the old bare `{v}`, or a key written as a class (`{.ws}`). Fixture: `02-attributes.json` "an unknown key is an error with a hint" and the three cases after it. | Use a key from the [attribute tables](fieldworks-markdown.md#attributes), or the class `.v`. |
+| `fwmd.syntax.duplicate-attribute` | error | A key appears twice, two keys set one property, or `.v` and `ws=` both name a writing system. Fixtures: `02-attributes.json` "a repeated key is an error", ".v and ws together name two writing systems". | Keep one. |
+| `fwmd.syntax.malformed-attribute` | error | An attribute block or a value that breaks the grammar; also bad front matter in a plain FieldWorks Markdown file. [Details](#malformed-attribute-in-detail). Fixture: `02-attributes.json` "a value that does not fit its key is malformed". | Write what the key takes (the message says which). |
+| `fwmd.syntax.unsupported-markup` | error | Pandoc reads a construct that FieldWorks text has no counterpart for. [Details](#unsupported-markup-in-detail). Fixture: `11-hardening.json` "math between dollar signs is a finding, because Pandoc reads it and the notation has none". | The fix escapes it (`\$x\$`, `\@`, `a\. palit`), where an escape keeps the text. |
+| `fwmd.syntax.too-deep` | error | A block, line or table is nested too deeply or is too large for the parser (Markdig's limit). One finding; the lines are kept as plain text. Fixture: `08-checks.json` "text nested deeper than the reader allows is one finding and its lines are kept as text". | Flatten the nesting or split the table. |
+| `fwmd.version.unsupported` | error | The front matter says `fwmd:` with a version newer than 1. Nothing else is read. Fixture: `06-front-matter.json` "a newer version is refused with a finding and nothing is read". | Read the file with a newer library. |
+| `fwmd.prop.unknown-number` | warning | A `pN` or `sN` key whose number is not a FieldWorks text property. The value is kept as written. Fixture: `02-attributes.json` "a property number that is not known is kept with a warning". | Check the number. Nothing to do if it is meant. |
+| `fwmd.record.record-file` | error | `MarkdownConverter.Parse` was given a [record file](record-files.md): the front matter has a top-level `record:` key. One finding on that line and nothing else is read, so a host cannot write back only the body. Fixture: `06-front-matter.json` "a record file whose record key is quoted is a record file". | Read the file with `RecordFileReader`. |
+
+### Malformed attribute in detail
+
+`fwmd.syntax.malformed-attribute` covers:
+
+- an attribute block that breaks the grammar: `{}`, `{#id}`, a bad escape;
+- a value that does not fit its key: `bold=yes`;
+- a unit key (`fontsizeUnit`) without its base key;
+- `url=` that is not a `silfw://` URL, on a link to an object of the project;
+- text after the block on a `:::` line;
+- in a plain FieldWorks Markdown file, the front matter: `fwmd` that is not a whole number, an empty or list default writing system, a
+  tab in the indentation, a line that is not a key and a value. In the front matter, indent with spaces.
+
+More fixtures: `06-front-matter.json` "a version that is not a number is malformed"; `11-hardening.json` "a tab in the front matter's
+indentation is malformed, because Pandoc refuses it".
+
+### Unsupported markup in detail
+
+`fwmd.syntax.unsupported-markup` covers raw HTML, a code span, a thematic break, a reference definition, a nested list, a div in a div,
+an unescaped block marker in a styled div, math, a citation, an inline note, strikeout, heading attributes, fancy list markers, line
+blocks, grid tables, definition lines, a table caption, a `:::` line straight after a paragraph line (the fix adds a blank line), a
+`[]{.empty}` that is not the whole paragraph, and a pipe table when the host names no table styles. Raw HTML, code and a thematic break
+have no fix: escape or remove them. See [Unsupported Pandoc constructs](fieldworks-markdown.md#unsupported-pandoc-constructs).
+
+## FieldWorks Markdown: blocks and fields
+
+| Id | Severity | Meaning | Usual fix |
+|---|---|---|---|
+| `fwmd.heading.too-deep` | error | A heading deeper than `###` has no paragraph style. Fixture: `04-structure.json` "a heading deeper than three has no style". | Use `###`, or a div with the style. |
+| `fwmd.table.ragged` | error | A row has another number of cells than the header, or the delimiter row has another width. Fixtures: `04-structure.json` "a row with another number of cells than the header is an error", "a delimiter row of another width than the header is an error with the delimiter row as the fix". | Add or remove cells. For the delimiter row the fix is one `---` per header cell. |
+| `fwmd.table.alignment` | error | A delimiter row with a colon (`:---:`). Alignment has nowhere to be stored. Fixture: `04-structure.json` "a column alignment has nowhere to be stored". | `---` (the fix). |
+| `fwmd.table.tab-in-cell` | error | A tab inside a cell, raw or as `&#9;`. In storage the tab is the cell separator. Fixtures: `04-structure.json` "a tab inside a cell cannot be stored", "a raw tab inside a cell cannot be stored either, although it would read as a space". | Use spaces. |
+| `fwmd.field.block-syntax` | error | `ParseInline` (a field of one paragraph, such as a multi-string field) met block syntax: a heading, a list, a div or a blank line. Fixtures: `08-checks.json` "a multi-string field takes inline grammar only: a heading is an error"; `11-hardening.json` "a multi-string field is one paragraph: a blank line is an error that asks for a hard line break". | Keep the text inline. For a line break, end the line with `\`. |
+
+The table findings need table styles (`MarkdownStyleNames.TableHeader` and `TableRow`). Without them a pipe table is
+`fwmd.syntax.unsupported-markup`.
+
+## FieldWorks Markdown: checks against the project
+
+These need the host's interfaces in `MarkdownOptions`. With the defaults (no project) they are never reported.
+
+| Id | Severity | Meaning | Usual fix |
+|---|---|---|---|
+| `fwmd.ws.unknown` | error | A writing system the project does not have: after `ws=`, in an empty-paragraph marker, as a front-matter default, or (in a record file) as a key of a per-writing-system field. Needs `IWritingSystemMapper.IsKnown` to say no. `Choices` lists the project's writing systems when the host implements `IKnownWritingSystems`. Fixtures: `08-checks.json` "a writing system the project does not have is an error with the project's systems as choices"; `11-hardening.json` "a default writing system in the front matter that the project lacks is as unknown as one after ws=". | Pick one of the choices. |
+| `fwmd.ws.unmarked-vernacular` | information | Unmarked text that looks vernacular. **The library never reports it.** The id is reserved for a host's checker, which makes the finding with `CreateDiagnostic`. | `[text]{.v}` if it is vernacular; otherwise nothing. |
+| `fwmd.style.unknown` | error | A `custom-style=` the project does not have, as a character or a paragraph style. Needs `MarkdownOptions.Styles`. `Nearest` names close styles when the host implements `IKnownStyles`. Fixtures: `08-checks.json` "a character style the project does not have is an error with the nearest names", "a paragraph style the project does not have is an error with the nearest names". | Use the nearest name. |
+| `fwmd.link.not-found` | error | A link path matches no object; a `silfw://` link has neither a GUID nor a path; a `motif://` link into another project has only a path. Fixtures: `05-links.json` "a path that matches nothing is an error"; `11-hardening.json` "a silfw link with neither a GUID nor a path is an error and the host is not asked". | Correct the path, or add `guid=`. |
+| `fwmd.link.ambiguous` | error | A path matches more than one object (a homograph written without its number). `Choices` lists each match with its GUID. Fixture: `05-links.json` "a path that matches several objects is an error with a choice for each". | Add the homograph number (`palit(2)`) or `guid=`. |
+| `fwmd.link.broken` | warning | The link is marked `.broken`, or its `guid=` is not an object of this project (with the default `UnknownGuidPolicy.MarkBroken`). The text is kept. Fixtures: `05-links.json` "a GUID this project does not know is a warning, and the link is kept for an agent's text", "a link marked broken is a warning, and is written with the flag while the target stays deleted". | Relink to an object that exists, or keep it broken. |
+| `fwmd.link.guid-mismatch` | error | The URL names one GUID and `guid=` another; or an external address has `guid=`. Fixtures: `05-links.json` "a URL that names one GUID and guid= another is an error, not a guess"; `11-hardening.json` "an external address with guid= is an error, not a link whose address is dropped". | Remove the wrong one. |
+| `fwmd.link.relative-without-base` | error | A link relative to the file, read with no `MarkdownOptions.LinkBase`. Fixture: `05-links.json` "a link relative to the file needs a base". | Give the reader a base, or write a root path. |
+| `fwmd.link.stale-path` | information | The GUID resolves, but the object is now at another path. The next write has the current path. Fixture: `05-links.json` "the GUID is the identity: an out-of-date path is information and the next write has the current path". | None needed. |
+| `fwmd.link.rebound` | information | With `UnknownGuidPolicy.RebindByPath` (interactive paste), an unknown GUID was bound to the one object at the link's path. Fixture: `05-links.json` "an interactive paste binds an unknown GUID by the one object at its path and says so". | None needed. |
+| `fwmd.link.url-rebuilt` | information | `guid=` names another object than the stored `url=`, so the URL was rebuilt from the GUID. Fixture: `05-links.json` "an editor who changes guid= makes the stored URL stale: it is rebuilt from the new GUID". | None needed. |
+| `fwmd.picture.unknown` | error | A picture the project does not hold. Fixture: `05-links.json` "a picture that is not in the project is an error". | Correct the path or the GUID. |
+
+## Record files: YAML
+
+All cases are in `records/02-traps.json`. A fix that "removes" something replaces it with nothing.
+
+| Id | Severity | Meaning | Usual fix |
+|---|---|---|---|
+| `fwmd.yaml.syntax` | error | YAML that does not parse. Nothing more is read. Only the id and the start line are stable; where the error sits is YamlDotNet's. Case: "YAML that does not parse is a syntax error, and nothing is read". | Correct the YAML. No fix is offered. |
+| `fwmd.yaml.tab` | error | A tab in the indentation of a front-matter line. The rest is read with each tab as a space. Case: "a tab after the indentation's spaces is an error too". | Two spaces per tab. The fix is offered only when the file then reads to the same tree. |
+| `fwmd.yaml.line-separator` | error | A raw U+2028, U+2029 or U+0085. One YAML reader breaks lines at them and another does not. Case: "a raw line separator in a rich block is an error whose fix is its character reference". | In a rich value, `&#x2028;` (the fix). Elsewhere, no fix. |
+| `fwmd.yaml.duplicate-key` | error | A key the mapping already has. The first is read. Case: "a duplicate key is an error; the first is read". | Remove the later pair (the fix; none when the pair shares a line). |
+| `fwmd.yaml.anchor` | error | An anchor (`&x`). Case: "an anchor is an error whose fix removes it". | Remove it. |
+| `fwmd.yaml.alias` | error | An alias (`*x`), usually a bound root such as `*palit` written without quotes. Case: "a bound root written plain is a YAML alias: an error whose fix quotes it". | `"*palit"`. |
+| `fwmd.yaml.tag` | error | A tag (`!!str`, `!x`). The schema types every value. Case: "a tag is an error whose fix removes it". | Remove it. |
+| `fwmd.yaml.merge-key` | error | A merge key (`<<`). It is not read. Case: "a merge key is an error whose fix removes it, since it is not read". | Remove its lines (no fix when it shares a line). |
+| `fwmd.yaml.folded` | error | A folded scalar (`>`), which rewrites line ends. Cases: "folded rich text rewrites line ends: an error whose fix is the literal block", "folded plain text: an error whose fix is the quoted string". | The value as it reads, spelled canonically. |
+| `fwmd.yaml.second-document` | error | A second YAML document: a `---` line with text after it, or a YAML block in the body (Pandoc merges it into the metadata). It is not read. Case: "a --- line with text after it starts a second YAML document: an error". | Remove it. |
+| `fwmd.yaml.too-deep` | error | YAML nested deeper than 64 levels. The deeper parts are not read. Case: "YAML nested past the reader's limit is an error". | Flatten it. |
+| `fwmd.yaml.comment-dropped` | information | A comment. It is dropped: the project has nowhere to keep it. Case: "comments are dropped with information whose fix removes them". | Remove it. |
+| `fwmd.yaml.unquoted` | information | A plain (unquoted) scalar where the schema expects text. It is read as the text it spells: `no` is "no", `1.10` is "1.10", `null` is "null". Case: "the Norway problem: a plain no in a text field is the text no, with information". | The value double-quoted (for a rich value, a block). |
+| `fwmd.yaml.scalar-style` | information | A value in a style that is not canonical: single quotes, other escapes, a quoted number or Boolean, a leading zero, an uppercase GUID, a needlessly quoted key, a rich value in the wrong kind of block. Cases: "a single-quoted value is read; it is written double-quoted", "012 in an integer field is twelve, written 12". | The canonical spelling. |
+| `fwmd.yaml.flow` | information | A flow collection (`{...}`, `[...]`, JSON). It is read; the writer writes block style. Case: "flow collections and JSON are read, with information". | None needed. |
+| `fwmd.yaml.empty` | information | An empty value (`key:`, `~`, `""`, `[]`, `{}`). It means the field is empty, which a canonical file says by leaving the key out. Case: "~ is an empty value, which is left out". | Remove the line, when the key has a line of its own. |
+| `fwmd.yaml.key-order` | information | Keys out of the schema's order (`guid` not first, fields out of order). Case: "keys out of the schema's order are read, with information". | None needed. |
+
+## Record files: the record
+
+All cases are in `records/03-schema.json` unless another file is named.
+
+| Id | Severity | Meaning | Usual fix |
+|---|---|---|---|
+| `fwmd.record.not-a-record` | error | The text is not a record file: no front matter, no closing line, or no `fwmd` or `record` key. Case: "plain FieldWorks Markdown (no record key) is not a record file". | Read it with `MarkdownConverter.Parse`. |
+| `fwmd.record.unknown-key` | error | A front-matter key a record file does not have. Case: "an unknown front-matter key is an error in a record file". | Remove it, or correct its spelling. |
+| `fwmd.record.unknown-kind` | error | A `record:` kind the schema does not have. Case: "a record kind the schema does not have". | Use a kind of the schema. |
+| `fwmd.record.schema-mismatch` | error | `schema:` names another schema than the reader's. Case: "a schema other than the reader's". | The reader's schema id (the fix). |
+| `fwmd.record.unknown-field` | error | A key an object of its type does not have. `Nearest` names close fields. Case: "an unknown field, with the nearest name". | Use the field's name. |
+| `fwmd.record.wrong-shape` | error | A mapping, list or scalar where the schema has another shape. Case: "a value of the wrong shape: a list where alternatives are expected, a string where an object is". | Write the shape the field takes. |
+| `fwmd.record.not-an-integer` | error | Not a whole number in an integer field. Case: "not a whole number in an integer field". | A whole number. |
+| `fwmd.record.not-a-boolean` | error | Not `true` or `false` in a Boolean field. For `yes`, `no`, `on`, `off` and other YAML 1.1 words the fix is the Boolean they mean. File `02-traps.json`, case "yes in a Boolean field is an error whose fix is true". | `true` or `false`. |
+| `fwmd.record.bad-guid` | error | Not a GUID in a GUID field. Case: "not a GUID in a GUID field". | A GUID, lowercase with hyphens. |
+| `fwmd.record.duplicate-guid` | error | One GUID on two objects of the file. Case: "one GUID on two objects". | Give each object its own GUID. |
+| `fwmd.record.not-a-reference` | error | A reference that is not one FieldWorks Markdown link. Case: "a reference that is not a link". | One link with `guid=`, double-quoted. |
+| `fwmd.record.plain-field-markup` | error | Formatting or another writing system in a plain-text value written as a block. A block holds plain text as FieldWorks Markdown only so that it can carry control characters. Case: "formatting in a plain text field written as a block is an error". | Remove the markup, or escape it (`\*`). |
+| `fwmd.record.unwritable` | error | A value or body the reader can read but the writer cannot spell: a rich value whose first line starts with a space, or that holds a tab, a control character or a line separator; a front-matter value or a writing-system key with a control character. File `04-unwritable.json`, case "a quoted rich value with a leading space reads, but cannot be written: an error whose fix spells what was read". | What was read, written again (the fix), where that reads back the same. |
+| `fwmd.record.bad-root` | error | A `root:` that is not a project path, or whose segments after the record's do not walk the schema (a sequence needs an index). Cases: "a root that does not walk the schema", "a root with a sequence and no index". | Correct the path. |
+| `fwmd.record.outside-root` | error | A key in `record-data:` outside the field a partial file's `root:` names. Case: "a key outside the field the root names". | Remove it, or widen the root. |
+| `fwmd.record.unexpected-body` | error | Text below the front matter of a record kind with no body field. Case: "text below the front matter of a record with no body field". | Move the text into a field, or remove it. |
+| `fwmd.record.body-in-frame` | error | The body field written in `record-data:`. Its value belongs in the body. Case: "the body field in record-data is an error". | Move the value below the front matter. |
+| `fwmd.record.block-not-allowed` | error | A table, list or heading in a rich field whose block features do not allow it (ADR 0033). One finding per block. File `05-blocks.json`, case "a table in a field that allows no blocks is an error, and its fix is one plain paragraph per row". | The block as plain paragraphs, flattened as paste does (the fix; none when the value is not a literal block). |
+| `fwmd.record.notation` | error | The default id of a host notation checker's finding that gives no code of its own. Case: "a notation finding with no code takes the default id". | What the checker's message says. |
+
+A host's notation checker usually gives its own codes. The fixtures' stub checker uses `fwmd.env.unknown-class`
+(`03-schema.json`, "a notation the host's checker refuses: its finding is placed in the file, through the quoting"). That id belongs to
+the fixture, not to the library.
+
+## LCModel adapter
+
+`SIL.TextEditing.LCModel` reports each property it leaves out of an `ITsString` or StyleRules because liblcm cannot load it back (ADR
+0016, amended). These are **not** `MarkdownDiagnostic`s. Each is a `DroppedProperty` passed to an optional `Action<DroppedProperty>`
+callback of `TsStringConversion.ToTsString`, `ToStyleRules`, `ToTextParagraphs` and `TsStringClipboard.FragmentToXml`, or to
+`TsStringClipboardForm.OnDropped`. A `DroppedProperty` has the property `Number`, `ParagraphIndex`, `RunIndex`, `Reason`, `Detail` and
+`Message`; it has no line, column or severity. With no callback the property is dropped silently. The run model's property bag keeps it
+either way.
+
+| Id | Meaning | Usual fix |
+|---|---|---|
+| `textediting.lcm.unstorable-property` | A property, or one value of it, that liblcm refuses was left out (`Reason` is `PropertyNotLoadable` or `ValueNotLoadable`). | Nothing in the text. A host that must keep the property needs its own storage. |
+| `textediting.lcm.replaced-property` | A refused `rightToLeft` (128) value in a paragraph's bag was stored as the paragraph's direction instead (`Reason` is `ValueReplaced`). The data is kept, in another form. | None needed. |
diff --git a/docs/formats/record-files.md b/docs/formats/record-files.md
new file mode 100644
index 0000000..e742ae1
--- /dev/null
+++ b/docs/formats/record-files.md
@@ -0,0 +1,389 @@
+# Record files
+
+A record file holds one FieldWorks record (a lexical entry, a notebook record, a list item), or part of one, as one text file (ADR 0032).
+The YAML front matter holds the tree of objects and fields. Every rich value in it is [FieldWorks Markdown](fieldworks-markdown.md). For a
+record kind with a main long-text field, that field is the Markdown body below the front matter.
+
+| | |
+|---|---|
+| File name | `*.fw.md`, like any FieldWorks Markdown file. A top-level `record:` key is what makes it a record file. |
+| API | `RecordFileReader.Read(text, schema, options)` and `RecordFileWriter.Write(document, schema)` in `SIL.TextEditing.Markdown.Records`. |
+| Schema | A `RecordSchema`, which is data. `RecordSchema.ToJsonSchema()` publishes it as a JSON Schema for editors. |
+| Defined by | The fixtures in `tests/conformance/records` (README "Record files"), ADRs 0032 and 0033. |
+| Status | Shipped: the frame, the schema, the findings and the fixtures. Planned: export from liblcm, diffs and shape checks, and the schema built from liblcm metadata (`SIL.TextEditing.Project`, ADR 0031). |
+
+`MarkdownConverter.Parse` refuses a record file with one finding, `fwmd.record.record-file`, so a host cannot write back only its body.
+Read it with `RecordFileReader`.
+
+The examples are copied from the fixtures, and `FormatDocsTests` checks them. They use the fixtures' schema `test.schema.json`
+(`records/schemas.json`, entry `test`) unless they say otherwise.
+
+## Editing a record file by hand
+
+1. Keep the lines `---`, `fwmd: 1`, `record:` and `schema:` as they are, and add no other top-level key.
+2. Put plain text in double quotes. Inside the quotes, write `\"` for a quote and `\\` for a backslash; nothing else needs escaping.
+3. Write rich text as a block: `|-` after the key, then the text on the next lines, indented two spaces more than the key. A field that
+   holds several paragraphs takes `|` instead, with a blank line between paragraphs.
+4. Indent with spaces, never tabs.
+5. To empty a field, delete its line. Do not leave `key:` with nothing after it.
+6. Do not change a `guid:`, and keep `guid=` on every link: the GUID is what the project matches.
+7. Do not use YAML comments, anchors (`&x`), aliases (`*x`), tags or `>` blocks. Comments are dropped; the others are errors.
+8. Read the file back with `RecordFileReader` (a command-line check is planned, #161). [Findings](findings.md) says what each finding
+   means.
+
+A small partial file. It holds one sense's gloss in two writing systems. The Norwegian id `no` is quoted, because YAML 1.1 readers take a bare `no` as
+"false":
+
+<!-- fixture: records/01-frame.json | a partial file whose root names a plain field: record-data holds that field only; the writing system no is a quoted key | file -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+root: "/lexicon/palit(2)/senses/1#gloss"
+record-data:
+  gloss:
+    en: "buy"
+    "no": "kjøper"
+---
+```
+
+## A whole record
+
+A notebook record. Its `description` field is the body. Its `conclusions` field holds paragraphs, so it is a `|` block in the frame.
+
+<!-- fixture: records/01-frame.json | a notebook record: its description is the Markdown body, its other long text a literal block of paragraphs (owner decision R-6) | file -->
+```markdown
+---
+fwmd: 1
+record: "notebook/record"
+schema: "test.schema.json"
+root: "/notebook/Kaon survey 2026-05"
+analysis: "en"
+vernacular: "ceb"
+writingSystems:
+  en:
+    lang: "en"
+    dir: "ltr"
+    font: "Charis SIL"
+  ceb:
+    lang: "ceb"
+    dir: "ltr"
+    font: "Charis SIL"
+record-data:
+  guid: "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
+  title: |-
+    Kaon survey, May 2026
+  type: "[Observation](/lists/record-types/Observation){guid=5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f}"
+  date-of-event: "2026-05-03"
+  researchers:
+    - "[J. Cruz](</lists/people/J. Cruz>){guid=6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a}"
+  conclusions: |
+    The northern speakers use [kaon]{.v} only for cooked rice.
+
+    The southern speakers use it for any meal.
+---
+
+## Observations
+
+On 3 May the speakers used [kaon]{.v} for every meal.
+```
+
+## The frame
+
+The front matter has these keys, and no others. The writer writes them in this order.
+
+| Key | Value |
+|---|---|
+| `fwmd` | The format version, `1`. A newer one is `fwmd.version.unsupported`. |
+| `record` | The record kind, a kind of the schema: `"lexicon/entry"`. Required. |
+| `schema` | The schema's id, which is also the JSON Schema's `$id`: `"test.schema.json"`. Another id is `fwmd.record.schema-mismatch`. |
+| `root` | What the file holds, as a project path. Absent: the whole record. See [Partial files](#partial-files). |
+| `base` | The export the file was made from, as text (a digest, such as `"sha256:9f2c41d0"`). |
+| `analysis`, `vernacular`, `writingSystems` | As in [FieldWorks Markdown](fieldworks-markdown.md#front-matter). They say what unmarked text and `.v` mean in every rich value. |
+| `record-data` | The record's objects and fields. |
+
+Any other key is `fwmd.record.unknown-key`. That rule holds in record files only; a plain FieldWorks Markdown file ignores keys it does
+not know.
+
+### Objects and fields
+
+- `record-data` is the root object. Its keys are the fields of the root type, in the schema's order.
+- An object of a type with GUIDs has `guid:` first: lowercase, with hyphens, double-quoted.
+- An owned object is a mapping. A sequence is a list. A field per writing system is a mapping from writing-system id to value.
+- A reference is one FieldWorks Markdown link with `guid=`, double-quoted.
+- Integers and Booleans are plain. A Boolean is only `true` or `false`.
+- Empty values are left out. An empty object in a list cannot be written; the writer refuses it.
+
+<!-- fixture: records/01-frame.json | integers and Booleans are plain, GUIDs lowercase and quoted, and the writer puts guid first and the fields in the schema's order | canonical -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+record-data:
+  guid: "abcdef00-1111-4222-8333-444455556666"
+  citation-form:
+    ceb: "x"
+  homograph-number: 3
+  do-not-use-for-parsing: true
+---
+```
+
+## Quoting
+
+The writer writes block style, two-space indentation and `\n` line ends. It never writes anchors, aliases, tags, flow collections or
+comments.
+
+- **Strings are double-quoted.** `\"` and `\\` are the only escapes. Every other character, YAML's special ones included, is itself:
+
+<!-- fixture: records/01-frame.json | a value with quotes, backslashes and YAML's special characters is double-quoted with only two escapes | file -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+record-data:
+  citation-form:
+    ceb: "a \"b\" c\\d: #e &f *g !h |i >j {k} [l] %m @n `o"
+---
+```
+
+- **Keys are bare** when they are an ASCII letter followed by ASCII letters, digits, `-`, `_` and `/`, and are not a word YAML 1.1 reads as a Boolean or
+  null. So the Norwegian writing system `no` is written `"no"`
+  (`records/01-frame.json`, "a partial file whose root names a plain field: record-data holds that field only; the writing system no is a
+  quoted key").
+- **The schema types every value**, not YAML. A plain `no` in a text field is the text "no", with the information `fwmd.yaml.unquoted`:
+
+<!-- fixture: records/02-traps.json | the Norway problem: a plain no in a text field is the text no, with information | file -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+record-data:
+  citation-form:
+    ceb: no
+---
+```
+
+  It is written:
+
+<!-- fixture: records/02-traps.json | the Norway problem: a plain no in a text field is the text no, with information | canonical -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+record-data:
+  citation-form:
+    ceb: "no"
+---
+```
+
+- **Characters no canonical file holds raw:** C0 and C1 controls (tab included), DEL, U+2028, U+2029, U+FEFF, U+FFFE and U+FFFF. One YAML
+  reader breaks lines at U+2028 and another does not. Plain text that holds one of them is written as a `|-` block of one paragraph of
+  inline FieldWorks Markdown, which spells it as a character reference:
+
+<!-- fixture: records/01-frame.json | plain text with a control character is a literal block of inline FieldWorks Markdown, which spells it as a character reference | canonical -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+record-data:
+  citation-form:
+    ceb: |-
+      pa&#x9;lit
+  computed:
+    headword: |-
+      a\
+      b
+---
+```
+
+  A plain-text value written as a block may not hold formatting (`fwmd.record.plain-field-markup`).
+
+## Rich text: `|` and `|-`
+
+A rich value is FieldWorks Markdown, written as a literal block in place (ADR 0032). The block header follows the field:
+
+| Field | Header | Pandoc reads it as | Read with |
+|---|---|---|---|
+| A rich field of paragraphs (an StText) | `\|` (clip) | blocks | `MarkdownConverter.Parse` |
+| A rich field of one paragraph (a MultiString or String) | `\|-` (strip) | inlines | `MarkdownConverter.ParseInline` |
+| Plain text that needs a block (above) | `\|-` | inlines | `ParseInline` |
+
+- A `|` block keeps one line end after its last line, and a `|-` block keeps none. Either way the value itself never ends with a line end:
+  the reader drops that one line end, and the writer adds it back for `|`.
+- Unmarked text in an alternative of a per-writing-system field means that alternative's writing system. In a field in one writing system
+  it means the field's default (`analysis` or `vernacular`, from the file's front matter). `.v` is the file's vernacular.
+- Block syntax in a field of one paragraph is `fwmd.field.block-syntax`.
+- The reader also takes a quoted rich value, another block header (`|+`, `|2-`) or a field of one paragraph in a `|` block, with the
+  information `fwmd.yaml.scalar-style` and the canonical block as the fix. A plain (unquoted) rich value gets `fwmd.yaml.unquoted`. A
+  folded block (`>`) is an error, `fwmd.yaml.folded`.
+
+<!-- fixture: records/02-traps.json | a rich value in a clip block (|) is read without its last line end; the canonical block is |- | file -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+record-data:
+  comment:
+    en: |
+      a note
+---
+```
+
+Here `comment` is a field of one paragraph, so the writer writes `|-`.
+
+## The body
+
+- A record kind whose schema names a **body field** writes that field as the Markdown body: one blank line after the front matter, ending
+  with a line end. In the fixtures, `notebook/record` has `description` and `lists/item` has `discussion`. `lexicon/entry` has none.
+- The body field is never in `record-data` (`fwmd.record.body-in-frame`).
+- Text below the front matter of a kind with no body is `fwmd.record.unexpected-body`. Blank lines are not a body.
+- The body is trimmed of spaces, tabs and line ends only. A no-break space at its end is text.
+- A YAML block in the body is `fwmd.yaml.second-document`: Pandoc would merge it into the metadata.
+
+## Partial files
+
+`root:` names what the file holds. Agents usually write partial files.
+
+- The first few segments of the path name the record. How many depends on the record kind: two for `lexicon/entry`
+  (`/lexicon/palit(2)`), three for `lists/item` (`/lists/GDR/GDR-47`).
+- Each further segment is a field of an owned object, followed by a 1-based index for a sequence: `/lexicon/palit(2)/senses/1`.
+  `record-data` then holds that object's fields.
+- A fragment names a field, and after a dot one writing system: `#gloss`, `#definition.en`.
+  - A fragment that names one rich value (a field in one writing system, or one alternative) makes that value the body.
+  - Any other fragment makes `record-data` hold that field only.
+- A root that does not walk the schema is `fwmd.record.bad-root`. A key outside the field the root names is `fwmd.record.outside-root`.
+
+<!-- fixture: records/01-frame.json | a partial file whose root names one alternative of a rich field: front matter only, and the value as a one-paragraph body | file -->
+```markdown
+---
+fwmd: 1
+record: "lexicon/entry"
+schema: "test.schema.json"
+root: "/lexicon/palit(2)/senses/1#definition.en"
+analysis: "en"
+vernacular: "ceb"
+---
+
+to pay money for [something]{.v}
+```
+
+## Read lenient, write strict
+
+- **Information** (`fwmd.yaml.unquoted`, `scalar-style`, `flow`, `empty`, `key-order`, `comment-dropped`): the file is read as it means,
+  and the writer spells it canonically. Comments are dropped, because the project has nowhere to keep them.
+- **Errors** for what YAML readers disagree on or what would lose data: tabs in indentation, raw line separators, duplicate keys, anchors,
+  aliases, tags, merge keys, folded blocks, a second document, nesting deeper than 64, and YAML that does not parse.
+- **Read, then write, is total.** A value the reader can read but the writer cannot spell is an error, `fwmd.record.unwritable`, whose
+  fix spells what was read. A file read with no error can always be written, and reads back the same.
+- Findings inside a rich value or the body keep the FieldWorks Markdown ids, placed in the file. Every id is in [Findings](findings.md).
+- `RecordReadOptions.Markdown` gives the project's writing systems, styles and objects for the rich values. `RecordReadOptions.Notations`
+  is the host's `INotationChecker` for notation fields.
+- Not checked yet: whether a reference resolves, its target's class, collection order, deletes and moves. They are planned.
+
+## Block features
+
+A rich field of paragraphs says which of tables, lists and headings it allows (ADR 0033). The default is all three. A field of one
+paragraph allows none. A block a field does not allow is `fwmd.record.block-not-allowed`, one finding per block, with a fix that flattens
+it as paste does. This case uses the schema `blocks` and the project `records-tables`, which names table styles:
+
+<!-- fixture: records/05-blocks.json | a table in a field that allows no blocks is an error, and its fix is one plain paragraph per row | file -->
+```markdown
+---
+fwmd: 1
+record: "notebook/record"
+schema: "blocks.schema.json"
+record-data:
+  plain: |
+    Intro.
+
+    | Name | Gloss |
+    |---|---|
+    | palit | buy |
+---
+```
+
+The fix replaces the table's lines with `Name | Gloss`, a blank line and `palit | buy`.
+
+## The schema is data
+
+A `RecordSchema` describes object types and record kinds. Hosts build one with `RecordSchemaBuilder`. The planned
+`SIL.TextEditing.Project` will build it from liblcm metadata. The fixtures give schemas as JSON in `records/schemas.json`, in a form the
+conformance README documents:
+
+<!-- fixture-excerpt: records/schemas.json -->
+```json
+          {
+            "name": "plain",
+            "kind": "rich",
+            "paragraphs": true,
+            "blocks": []
+          },
+```
+
+| Field kind | Builder | Value in the file |
+|---|---|---|
+| `Text` | `Text`, `MultiText`, `Texts` | double-quoted plain text |
+| `Rich` | `Rich`, `MultiRich` (`paragraphs`, `blocks`) | FieldWorks Markdown in a `\|` or `\|-` block |
+| `Notation` | `Notation`, `MultiNotation`, `Notations` | double-quoted text the host's checker reads (an environment, a feature structure) |
+| `Integer`, `Boolean`, `Guid` | `Integer`, `Boolean`, `Guid` | plain number, `true`/`false`, quoted lowercase GUID |
+| `Reference` | `Reference`, `References` | one FieldWorks Markdown link with `guid=`, double-quoted |
+| `Object` | `Object`, `Objects` | a mapping of the object type's fields |
+| `Sequence` | `Objects`, `References`, `Texts`, `Notations` | a list |
+
+- An object type has fields in canonical order and `HasGuid` (default true).
+- A record kind has a name (`record:`), a root type, how many path segments name a record (`pathSegments`) and an optional body field (`RecordSchemaBuilder.Kind`).
+- A text field in one writing system has a default: `RecordWritingSystem.Analysis` or `Vernacular`.
+- A field name has no `.`, `/`, `#`, space or control character, because those delimit field paths (`senses/1/definition.en`).
+
+## JSON Schema export
+
+`RecordSchema.ToJsonSchema()` writes a JSON Schema (draft-07) of the front matter, for editors and checkers. The same
+schema always gives the same bytes. `records/test.schema.json` is the fixtures' `test` schema, byte for byte.
+
+- `$id` is the schema's id. `record` is an enum of the kinds. `schema` is a constant. Unknown front-matter keys are not allowed.
+- One definition per object type. For each kind, an `if`/`then` gives `record-data` its type when `root` is absent or names the record
+  itself. A kind with a body uses a `<type>--frame` definition that leaves the body field out.
+- Every text value has `contentMediaType`:
+
+| Value | `contentMediaType` |
+|---|---|
+| Plain text | `text/plain` |
+| Rich text of paragraphs | `text/x-fieldworks-markdown` |
+| Rich text of one paragraph, and a reference | `text/x-fieldworks-markdown-inline` |
+| A notation | `text/x-fieldworks-<notation>`, such as `text/x-fieldworks-environment` |
+
+- A rich field of paragraphs that does not allow every block kind has `x-fieldworks-blocks`, the kinds it allows (`[]`, `["lists"]`, ...).
+  A field that allows all has none.
+
+<!-- fixture-excerpt: records/blocks.schema.json -->
+```json
+        "plain": {
+          "type": "string",
+          "contentMediaType": "text/x-fieldworks-markdown",
+          "x-fieldworks-blocks": []
+        },
+        "lists-only": {
+          "type": "string",
+          "contentMediaType": "text/x-fieldworks-markdown",
+          "x-fieldworks-blocks": ["lists"]
+        },
+```
+
+VS Code's YAML extension does not validate Markdown front matter by itself. Validating record files against the JSON Schema from the
+command line is planned: the fwmd CLI (#161).
+
+## What the tests hold the format to
+
+- `RecordConformanceTests` runs every case: the document read, the findings, and the canonical text written back byte for byte.
+- `RecordGateTests`: YamlDotNet's representation model reads each canonical front matter to the same tree; Pandoc (with the flags in
+  [Relation to Pandoc](fieldworks-markdown.md#relation-to-pandoc)) reads each canonical file, its rich values and its body as the reader
+  does; a whole-record canonical file validates against the published JSON Schema.
+- `RecordFuzzTests` mutates the canonical cases (seeded). The reader never throws, and a mutated file it reads without an error writes and
+  reads back without one.
diff --git a/docs/formats/tables.md b/docs/formats/tables.md
new file mode 100644
index 0000000..43705ca
--- /dev/null
+++ b/docs/formats/tables.md
@@ -0,0 +1,132 @@
+# Tables
+
+FieldWorks text has no table object. This page says how a table is stored today, how FieldWorks Markdown writes it, and the planned
+design for real tables in the field.
+
+## How a table is stored now
+
+A table is a run of paragraphs, one per row:
+
+- The header row is a paragraph in the host's **table header style**. Each body row is a paragraph in its **table row style**.
+- Cells are separated by a tab (U+0009) in the row's text.
+- The host names the two styles (`MarkdownStyleNames.TableHeader` and `TableRow`). They have no default. Motif's are the GDR template's,
+  `GDR Table Header` and `GDR Table Row`, which the fixtures use.
+- A host with no table styles has no tables: a pipe table is `fwmd.syntax.unsupported-markup`, its rows are read as `Normal`, and the
+  writer never writes a pipe table.
+
+## In FieldWorks Markdown
+
+A table is a pipe table: a header row, a delimiter row of plain `---`, and the body rows. Each cell holds inline text only.
+
+<!-- fixture: 04-structure.json | a table is a header row, a delimiter row and body rows, one paragraph per row with tab-separated cells | markdown -->
+```markdown
+| Form | Gloss |
+|---|---|
+| [palit]{.v} | change |
+| [mamalit]{.v custom-style="Emphasized Text"} | buy \| sell |
+```
+
+- A `|` in a cell that is not a separator is `\|`, in text, in a quoted value and in a link destination.
+- The reader takes any pipe table Pandoc reads; the writer writes the canonical form:
+
+<!-- fixture: 04-structure.json | a table delimiter with spaces and a leading pipe missing is read and written as plain dashes | markdown -->
+```markdown
+A | B
+--- | ---
+1 | 2
+```
+
+<!-- fixture: 04-structure.json | a table delimiter with spaces and a leading pipe missing is read and written as plain dashes | canonical -->
+```markdown
+| A | B |
+|---|---|
+| 1 | 2 |
+```
+
+- A header row in the middle of rows starts a new table (`04-structure.json`, "a header row in the middle of rows starts a new table").
+- One column and empty cells are allowed.
+
+### Errors
+
+| Id | When |
+|---|---|
+| `fwmd.table.ragged` | A row, or the delimiter row, has another number of cells than the header. |
+| `fwmd.table.alignment` | The delimiter row has a colon (`:---:`). Alignment has nowhere to be stored. |
+| `fwmd.table.tab-in-cell` | A cell holds a tab, raw or `&#9;`. The tab is the separator in storage. |
+| `fwmd.syntax.too-deep` | The table is too large for Markdig (rows × (columns + 1) over about 10,200). |
+| `fwmd.syntax.unsupported-markup` | The host has no table styles; or a `Table:` caption, or a grid table. |
+
+### Rows that cannot be a pipe table
+
+The writer puts a table-style paragraph in a div when a pipe table cannot carry it exactly:
+
+- a row with no header row above it (an orphan row);
+- a header whose cells are all empty (Pandoc reads such a header as no header);
+- a row whose tab is not plain analysis text (inside a span or a link), so it cannot be a cell separator;
+- a row with a hard line break in a cell;
+- an empty row whose writing system is not the default;
+- a table too large for Markdig.
+
+In a div the cells are separated by tab references:
+
+<!-- fixture: 04-structure.json | an orphan table row is a div with the row style, its cells separated by tab references | canonical -->
+```markdown
+::: {custom-style="GDR Table Row"}
+a&#x9;b
+:::
+```
+
+<!-- fixture: 04-structure.json | a tab that is not plain analysis text cannot be a cell separator, so that row is left to a div | canonical -->
+```markdown
+| x | y |
+|---|---|
+
+::: {custom-style="GDR Table Row"}
+[a&#x9;]{.v}b
+:::
+```
+
+## Fields that do not allow tables
+
+A field's block features say whether it may hold tables, lists and headings (ADR 0033; `BlockFeatures`). When tables are off:
+
+- A paste, and so a Markdown paste, **flattens** a table: one plain paragraph per row, the cells joined by a space, a bar and a space
+  (`a | b`; an empty cell gives `a |  | b`). The field raises `BlocksFlattened`.
+- A table already in the field is kept.
+- In a record file, a table in a rich field that does not allow it is `fwmd.record.block-not-allowed`. Its fix is the same flattening
+  (`records/05-blocks.json`).
+- `StyleBlockRecognizer.Default` names no table style. A host that turns tables off gives the field a recogniser that knows its table
+  styles, such as `MarkdownStyleNames.ToBlockRecognizer()`.
+
+The owner's decision in ADR 0033 sets the planned defaults, which the planned `SIL.TextEditing.Project` will compute from liblcm metadata: tables (and
+lists and headings) on in every multi-paragraph field, except the interlinear baseline (`Text.Contents`) and Scripture; off in a field of
+one paragraph. Hosts may override per field. The enforcement is built; the defaults from liblcm are not.
+
+## Planned: real tables in the field
+
+> **Planned. Not built.** ADR 0031 lists real tables as a planned addition. The work is tracked from issue #152.
+
+The owner decided on 2026-11-05:
+
+- The field edits real tables. They are stored so that the core data model does not change and older FieldWorks versions can still open
+  and read the text.
+- Each row is one paragraph. Cells are separated by a ` | ` run in a separator character style.
+- The Markdown side stays a standard pipe table. Storage reuses the existing `Table Row` paragraph style, plus a header-row style and a
+  `Table Cell Separator` character style. The host can rename them. USFM table markers are not used.
+- Tab moves to the next cell. Tab in the last cell adds a row, as in Word.
+- Enter and Shift+Enter both insert a hard line break (U+2028) in a cell. Enter on an empty last row leaves the table.
+- Nothing more in the first version: no alignment, widths or merged cells unless asked for again. The caption is kept.
+- Tab-separated text pasted at a paragraph boundary becomes a table. "Paste as table" is offered too.
+- Which fields allow tables is above. The block-features switch and its enforcement are built (ADR 0033).
+
+**Proposed, not decided:**
+
+- **The boundary rule.** A cell boundary is each `|` inside a run in the separator style; the spaces around it are padding. The rule counts
+  bars, not runs, because two separators around an empty cell merge into one run (` |  | `). A `|` without the style is cell text.
+- **Older FieldWorks** shows each row as one line of text, `Name | Gloss | Notes`, and keeps the separators through its own copy and paste.
+- **Reading old data.** The reader still accepts the tab form, so existing text keeps working; the writer writes the separator form.
+- **Markdown.** Pipe tables stay canonical. A table with a line break in a cell would be written as a grid table. `fwmd.table.tab-in-cell`
+  keeps its tab half. `fwmd.table.alignment` stays an error while alignment has nowhere to be stored.
+- **Editing.** A table is a view over the flat list of paragraphs, with one undo step per command.
+- **Flattening agrees.** The flattened text of a disallowed table (`a | b`) is already the text the styled separator gives, so the two
+  forms agree.
diff --git a/tests/SIL.TextEditing.Markdown.Tests/FormatDocsTests.cs b/tests/SIL.TextEditing.Markdown.Tests/FormatDocsTests.cs
new file mode 100644
index 0000000..ba44f92
--- /dev/null
+++ b/tests/SIL.TextEditing.Markdown.Tests/FormatDocsTests.cs
@@ -0,0 +1,143 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text.RegularExpressions;
+using SIL.TextEditing.Markdown.Tests.Conformance;
+using Xunit;
+
+namespace SIL.TextEditing.Markdown.Tests
+{
+    /// <summary>Keeps the format documentation in docs/formats honest: every finding id the source can report has a row in the catalogue (findings.md) and every
+    /// id in a table of findings.md or tables.md is in the source; every fixture marker is well-formed; and every
+    /// example marked with a fixture comment is, character for character, the text of that fixture case. Both read the repository from disk, so they find the
+    /// ids of every project (the LCModel adapter's too) without referencing it.</summary>
+    public class FormatDocsTests
+    {
+        // A whole id in a string literal: "fwmd.syntax.unclosed-mark", "textediting.lcm.unstorable-property". A prefix such as "fwmd.table." ends in a dot and is
+        // not an id.
+        static readonly Regex IdLiteral = new Regex("\"((?:fwmd|textediting)\\.[a-z0-9.-]*[a-z0-9])\"", RegexOptions.CultureInvariant);
+
+        // <!-- fixture: 05-links.json | case name | markdown --> before a fenced block. The field is markdown, canonical or file.
+        static readonly Regex FixtureComment = new Regex(@"<!-- fixture: (?<file>[^|]+?) \| (?<name>.+?) \| (?<field>markdown|canonical|file) -->\n```[a-z]*\n(?<text>.*?)\n```",
+            RegexOptions.Singleline | RegexOptions.CultureInvariant);
+
+        // <!-- fixture-excerpt: records/blocks.schema.json --> before a fenced block that is part of that fixture file, as it stands.
+        static readonly Regex ExcerptComment = new Regex(@"<!-- fixture-excerpt: (?<file>[^ ]+) -->\n```[a-z]*\n(?<text>.*?)\n```",
+            RegexOptions.Singleline | RegexOptions.CultureInvariant);
+
+        static string RepositoryRoot()
+        {
+            var dir = new DirectoryInfo(AppContext.BaseDirectory);
+            while (dir != null && !File.Exists(Path.Combine(dir.FullName, "SIL.TextEditing.sln"))) dir = dir.Parent;
+            return dir?.FullName ?? throw new InvalidOperationException("SIL.TextEditing.sln is not above " + AppContext.BaseDirectory);
+        }
+
+        static string ReadText(string path) => File.ReadAllText(path).Replace("\r\n", "\n");
+
+        static string FormatsDirectory => Path.Combine(RepositoryRoot(), "docs", "formats");
+
+        // An id in the first column of a table row: | `fwmd.table.ragged` | ...
+        static readonly Regex TableRowId = new Regex(@"^\| `((?:fwmd|textediting)\.[a-z0-9.-]*[a-z0-9])` \|", RegexOptions.Multiline | RegexOptions.CultureInvariant);
+
+        // Any line that starts a fixture marker, well-formed or not.
+        static readonly Regex AnyMarker = new Regex(@"<!--\s*fixture", RegexOptions.CultureInvariant);
+
+        static SortedSet<string> SourceIds()
+        {
+            var ids = new SortedSet<string>(StringComparer.Ordinal);
+            foreach (string path in Directory.GetFiles(Path.Combine(RepositoryRoot(), "src"), "*.cs", SearchOption.AllDirectories))
+                foreach (Match m in IdLiteral.Matches(ReadText(path))) ids.Add(m.Groups[1].Value);
+            return ids;
+        }
+
+        static List<string> TableIds(string doc) => TableRowId.Matches(ReadText(Path.Combine(FormatsDirectory, doc))).Cast<Match>().Select(m => m.Groups[1].Value).ToList();
+
+        [Fact]
+        public void EveryFindingIdInTheSourceIsInTheCatalogue()
+        {
+            var ids = SourceIds();
+            Assert.NotEmpty(ids);
+            var listed = new HashSet<string>(TableIds("findings.md"), StringComparer.Ordinal);
+            var missing = ids.Where(id => !listed.Contains(id)).ToList();
+            Assert.True(missing.Count == 0, "docs/formats/findings.md has no table row for: " + string.Join(", ", missing));
+        }
+
+        [Fact]
+        public void EveryFindingIdTheDocsListIsInTheSource()
+        {
+            var ids = SourceIds();
+            var catalogue = new HashSet<string>(TableIds("findings.md"), StringComparer.Ordinal);
+            var problems = new List<string>();
+            foreach (string doc in new[] { "findings.md", "tables.md" })
+            {
+                var listed = TableIds(doc);
+                Assert.True(listed.Count > 0, doc + " lists no finding id in a table.");
+                foreach (string id in listed)
+                {
+                    if (!ids.Contains(id)) problems.Add(doc + ": " + id + " is not in the source");
+                    if (!catalogue.Contains(id)) problems.Add(doc + ": " + id + " is not in findings.md");
+                }
+            }
+            Assert.True(problems.Count == 0, string.Join("\n", problems));
+        }
+
+        [Fact]
+        public void EveryFixtureMarkerIsWellFormed()
+        {
+            var problems = new List<string>();
+            foreach (string doc in Directory.GetFiles(FormatsDirectory, "*.md"))
+            {
+                string text = ReadText(doc);
+                int markers = AnyMarker.Matches(text).Count;
+                int understood = FixtureComment.Matches(text).Count + ExcerptComment.Matches(text).Count;
+                if (markers != understood)
+                    problems.Add(Path.GetFileName(doc) + ": " + markers + " fixture markers, but only " + understood + " are a well-formed marker followed by a fenced block");
+            }
+            Assert.True(problems.Count == 0, string.Join("\n", problems));
+        }
+
+        [Fact]
+        public void EveryMarkedExampleIsTheTextOfItsFixtureCase()
+        {
+            int checkedExamples = 0;
+            var problems = new List<string>();
+            foreach (string doc in Directory.GetFiles(FormatsDirectory, "*.md"))
+            {
+                foreach (Match m in FixtureComment.Matches(ReadText(doc)))
+                {
+                    checkedExamples++;
+                    string file = m.Groups["file"].Value, name = m.Groups["name"].Value, field = m.Groups["field"].Value;
+                    string where = Path.GetFileName(doc) + ": " + file + " \"" + name + "\" " + field;
+                    string path = Path.Combine(RepositoryRoot(), "tests", "conformance", file.Replace('/', Path.DirectorySeparatorChar));
+                    if (!File.Exists(path)) { problems.Add(where + ": no such fixture file"); continue; }
+                    var found = Json.Arr(Json.Parse(ReadText(path))).Select(Json.Obj).FirstOrDefault(c => Json.Str(c["name"]) == name);
+                    if (found == null) { problems.Add(where + ": no such case"); continue; }
+                    // A canonical of null means the input is canonical.
+                    string? text = Json.OptStr(found, field) ?? (field == "canonical" && found.ContainsKey("canonical") ? Json.OptStr(found, "markdown") ?? Json.OptStr(found, "file") : null);
+                    if (text == null) { problems.Add(where + ": the case has no " + field); continue; }
+                    if (text.TrimEnd('\n') != m.Groups["text"].Value) problems.Add(where + ": the example differs from the fixture");
+                }
+            }
+            Assert.True(problems.Count == 0, string.Join("\n", problems));
+            Assert.True(checkedExamples > 0, "No example in docs/formats is marked with its fixture.");
+        }
+
+        [Fact]
+        public void EveryMarkedExcerptIsPartOfItsFixtureFile()
+        {
+            var problems = new List<string>();
+            foreach (string doc in Directory.GetFiles(FormatsDirectory, "*.md"))
+            {
+                foreach (Match m in ExcerptComment.Matches(ReadText(doc)))
+                {
+                    string file = m.Groups["file"].Value;
+                    string path = Path.Combine(RepositoryRoot(), "tests", "conformance", file.Replace('/', Path.DirectorySeparatorChar));
+                    if (!File.Exists(path)) problems.Add(Path.GetFileName(doc) + ": " + file + ": no such fixture file");
+                    else if (ReadText(path).IndexOf(m.Groups["text"].Value, StringComparison.Ordinal) < 0) problems.Add(Path.GetFileName(doc) + ": " + file + ": the excerpt is not in the file");
+                }
+            }
+            Assert.True(problems.Count == 0, string.Join("\n", problems));
+        }
+    }
+}