Lead with what people and agents edit: a Markdown tab in the playground and README

README.md

@@ -11,19 +11,52 @@ Pandoc reads the same way the library does. The host owns the data and the undo
 
 **Status: unreleased. The API will change.** Everything outside the [Roadmap](#roadmap) is built and tested today.
 
-![Latin and Arabic in one paragraph, with one selection running across the direction changes](docs/images/bidi-selection.png)
+![Latin and Arabic in one paragraph with one selection running across the direction changes, and the same text as FieldWorks Markdown beside it](docs/images/bidi-selection.png)
 
 | | |
 |---|---|
 | ![Hindi, Tamil and Thai shaping](docs/images/indic-thai-shaping.png) | ![Inline pictures in left-to-right and right-to-left text](docs/images/inline-pictures.png) |
 | [Hindi, Tamil and Thai, shaped, with a conjunct selected as one cluster](docs/images/README.md) | [Inline pictures in left-to-right and right-to-left text](docs/images/README.md) |
-| ![Runs with unknown properties and the live inspector](docs/images/unknown-properties-inspector.png) | ![Spelling squiggles](docs/images/spelling-squiggles.png) |
+| ![Runs with unknown properties and the model tab](docs/images/unknown-properties-inspector.png) | ![Spelling squiggles](docs/images/spelling-squiggles.png) |
 | [Properties the editor does not know survive every edit](docs/images/README.md) | [Spelling per writing system; blue where a word mixes two](docs/images/README.md) |
 | ![The phonological-environment box](docs/images/environment-box.png) | ![Headings, lists and tables with their switches](docs/images/block-features.png) |
 | [A notation box with a language service: chips and diagnostics](docs/images/README.md) | [Tables, lists and headings, switched on or off per field](docs/images/README.md) |
 | ![The playground inside a WinForms form](docs/images/host-winforms-fieldworks-shape.png) | ![Composed and decomposed text and emoji](docs/images/nfd-surrogates.png) |
 | [Inside WinForms on .NET Framework 4.8: FieldWorks' shape](docs/images/README.md) | [NFD, stacked marks and surrogate pairs](docs/images/README.md) |
 
+## What people and agents edit
+
+The first paragraph of the picture above, as FieldWorks Markdown, the form a person or an AI agent reads and edits:
+
+```markdown
+The word [كتاب]{ws=ar} means book; [مرحبا بالعالم]{ws=ar} means hello world.
+```
+
+Unmarked text is the analysis writing system (English here); `[...]{ws=ar}` is another writing system and `[...]{.v}` the vernacular. A new
+run starts wherever the writing system or a property changes, so nothing numbers runs or records offsets. The two right-to-left
+paragraphs of the picture share one `::: {rightToLeft=1}` block. A file adds a short front matter, generated by the writer, that names the
+writing systems ([the format](docs/formats/fieldworks-markdown.md)).
+
+The same text has four forms, and only the first two are meant to be edited by hand:
+
+| Form | What it is for | Edited by hand |
+|---|---|---|
+| **FieldWorks Markdown** (`*.fw.md`) | People, AI agents, files and diffs; Pandoc reads it the same way | Yes |
+| **Record file** | A whole FieldWorks record: a YAML frame whose rich values are FieldWorks Markdown ([record files](docs/formats/record-files.md)) | Yes |
+| **`Document`, `Paragraph`, `Run`** | The editor's model in memory: per run the text, writing system and property bag; per paragraph the host's key | No: the playground's "Model (debug)" tab dumps it |
+| **liblcm `ITsString`** | FieldWorks' storage; the LCModel adapter maps it to and from the run model | No |
+
+**An agent's edit** is a text edit. Change the gloss and mark a vernacular word:
+
+```diff
+-The word [كتاب]{ws=ar} means book; [مرحبا بالعالم]{ws=ar} means hello world.
++The word [كتاب]{ws=ar} means [kitabu]{.v}; [مرحبا بالعالم]{ws=ar} means hello world.
+```
+
+The reader checks it: a malformed span or an unknown writing system is a finding with a line, a column and, where one exists, the exact
+fix ([findings](docs/formats/findings.md)), and nothing is applied while there is an error. The host applies the rest as one undo step. In
+the playground, edit the Markdown tab and press Apply; `MarkdownTabTests` makes this very edit.
+
 ## Why it's different
 
 - **A writing system on every run.** A `Run` holds text, a writing-system id, a property bag keyed by FieldWorks property numbers, and
@@ -75,7 +108,8 @@ run desktop10 --scenario "Inline picture (ORC)"
 ```
 
 `run.cmd` and `run.ps1` build the host and start it. The playground opens ready-made scenarios (bidi, Indic and Thai shaping, NFD, inline pictures, unknown properties, spelling, the
-environment box, long documents) with a live model inspector. The Pandoc tests need `pandoc` on `PATH`.
+environment box, long documents). Beside the field, the Markdown tab shows the field as FieldWorks Markdown, which you can edit and apply,
+and the Model tab shows its runs. The Pandoc tests need `pandoc` on `PATH`.
 
 ## Projects
 
@@ -115,8 +149,8 @@ Planned, not built:
   ([ADR 0031](docs/adr/0031-shared-editing-and-interchange-layer.md), [ADR 0033](docs/adr/0033-block-features.md)).
 - **The `fwmd` command-line checker** ([#161](https://github.com/sillsdev/SIL.TextEditing/issues/161)).
 - **The FieldWorks Markdown clipboard form** ([#168](https://github.com/sillsdev/SIL.TextEditing/issues/168)).
-- **Editor integration**: an inline WYSIWYG and Markdown source mode, and a VS Code extension with a language server. The plan and a proposed ADR
-  are awaiting owner decisions ([#170](https://github.com/sillsdev/SIL.TextEditing/issues/170)).
+- **Editor integration**: an inline WYSIWYG and Markdown source mode, and a VS Code extension with a language server. The playground's
+  Markdown tab is a host-side sketch of the source mode. The plan and a proposed ADR are awaiting owner decisions ([#170](https://github.com/sillsdev/SIL.TextEditing/issues/170)).
 - **Retiring the liblcm refusals** once FieldWorks pins a liblcm with its fixes [#410](https://github.com/sillsdev/liblcm/issues/410), [#413](https://github.com/sillsdev/liblcm/issues/413) and [#414](https://github.com/sillsdev/liblcm/issues/414) ([#159](https://github.com/sillsdev/SIL.TextEditing/issues/159)).
 
 ## Contributing

docs/images/README.md

@@ -4,24 +4,24 @@ Pictures of the playground (`samples/SIL.TextEditing.Playground`) for the README
 
 ## The headless ones
 
-Rendered by `tests/SIL.TextEditing.Playground.Tests/ScreenshotGenerator.cs`: a 1280 x 800 headless Avalonia 12 window (net10.0, Skia, Fluent light theme, the playground's own fonts: Segoe UI, Nirmala UI, Leelawadee UI), cropped to the field and the inspector beside it. The test is skipped unless `TEXTEDITING_SCREENSHOTS=1`, so the normal test run never writes here.
+Rendered by `tests/SIL.TextEditing.Playground.Tests/ScreenshotGenerator.cs`: a 1280 x 800 headless Avalonia 12 window (net10.0, Skia, Fluent light theme, the playground's own fonts: Segoe UI, Nirmala UI, Leelawadee UI), cropped to the field and the tabs beside it (Markdown, or Model for the run dump). The test is skipped unless `TEXTEDITING_SCREENSHOTS=1`, so the normal test run never writes here.
 
 ```powershell
 $env:TEXTEDITING_SCREENSHOTS=1; dotnet test tests\SIL.TextEditing.Playground.Tests -c Release -f net10.0 --filter ScreenshotGenerator
 ```
 
-- `bidi-selection.png`: Latin and Arabic in one paragraph, one selection running across the direction changes ("Latin and Arabic" scenario).
+- `bidi-selection.png`: Latin and Arabic in one paragraph, one selection running across the direction changes ("Latin and Arabic" scenario), with the same text as FieldWorks Markdown in the Markdown tab.
 - `indic-thai-shaping.png`: Hindi, Tamil and Thai shaped correctly, with a Devanagari conjunct selected as one cluster.
 - `nfd-surrogates.png`: composed and decomposed accents, stacked marks, and emoji (surrogate pairs and a ZWJ family), with the emoji selected.
 - `inline-pictures.png`: inline picture objects (U+FFFC) in left-to-right and right-to-left text, selected along with the text around them.
-- `unknown-properties-inspector.png`: runs that carry properties the editor does not understand (9001, 9002), a paragraph style and a character style, and the live inspector showing the run model.
+- `unknown-properties-inspector.png`: runs that carry properties the editor does not understand (9001, 9002), a paragraph style and a character style, and the Model tab showing the runs and their property numbers.
 - `environment-box.png`: the phonological-environment box, one line with coloured chips and a squiggle on a class the language service rejects.
 - `environment-fix-menu.png`: right-click on a problem in the environment box: the service's message, its fix ("Insert the closing parenthesis") and the Insert items.
 - `spelling-squiggles.png`: red squiggles on misspelled words, blue on a word that glues two writing systems, nothing on do-not-check or read-only text.
 - `spelling-context-menu.png`: the context menu on a misspelled word: the word, its suggestions, Find, Cut, Copy, Paste and Copy as.
 - `copy-as-submenu.png`: the "Copy as" submenu open (plain text, a debug dump of the runs, and a disabled Markdown entry when no converter is registered).
 - `block-features.png`: a heading, a bulleted list and a table (as table-styled paragraphs, one column for now) with the Tables, Lists and Headings switches visible and on.
-- `long-document.png`: the 200-paragraph scenario scrolled to the caret in the middle, mixed writing systems; the inspector says "paragraphs 200".
+- `long-document.png`: the 200-paragraph scenario scrolled to the caret in the middle, mixed writing systems; the Markdown tab shows the document as FieldWorks Markdown from its start.
 - `many-fields.png`: fifty small fields in one window, in English, French, Swahili and Arabic.
 
 ## The real windows