[johnml1135]

Start here: README.md, then docs/reference/README.md.

The README now introduces the project instead of documenting it. It has a pitch, a hero image and a gallery of 8 screenshots, and "Why it's different" in seven points, each backed by a test count or an ADR. Then come the quick start, a one-line-per-project table, a docs map, the roadmap, contributing and the licence. The long reference prose moved to docs/reference/ (10 pages). Nothing was dropped: where docs/formats (#166) already says it, the reference links there.

This branch merges #165 and #166 locally (git merge origin/docs/screenshots origin/docs/formats), so the images and format links resolve. Their commits show in this diff until they land. I'll rebase after.

Evidence, 2026-11-06, main 7ffd8f6 + #165 + #166, dotnet test SIL.TextEditing.sln -c Release with CI=true: 0 failures. Per target: Tests 416/416, Avalonia 777 (net48) / 778 (net10.0), Markdown 3841/3841, LCModel 111/111, Playground 304/304 (11 skipped), SecondDispatcher 3. The 667 *Pandoc* tests ran against Pandoc 3.9.0.2. A link check over README, AGENTS.md, docs/reference, docs/formats and docs/images/README found 137 relative links and images, 0 broken (anchors checked against GitHub heading slugs).

Next: rebase on main once #165 and #166 merge, then merge after review.

Where each old README section went

Old section	Now
Intro: run model shape, host owns undo	README pitch; docs/reference/run-model.md
Status: bootstrap	README status line ("unreleased, the API will change")
Projects table (long cells)	README one-line table; docs/reference/projects.md, lcmodel.md, markdown.md
One source tree, per-version differences, sample-only packages	docs/reference/avalonia-versions.md (now lists every #if NET10_0_OR_GREATER site in src)
The run model	docs/reference/run-model.md
Build and test, Try it	README quick start; WSL and font notes in projects.md
FieldWorks editing semantics	docs/reference/editing.md
Clipboard	docs/reference/clipboard.md, linking docs/formats/clipboard.md
Block features, Keyboards, Host hooks	docs/reference/editing.md
Spell checking, Language service	docs/reference/spelling-and-language-service.md
Colours and themes	docs/reference/rendering.md
Known gaps: accessibility, input, undo	docs/reference/limitations.md
Known gaps: selection, word rule	docs/reference/editing.md#selection
Known gaps: Avalonia faults	docs/reference/avalonia-versions.md
Known gaps: properties, trailing spaces, long paragraphs, graphemes	docs/reference/rendering.md
Licence	README licence

Facts that now live only in docs/formats (from #166)

These are linked from docs/reference/markdown.md and clipboard.md and not repeated. If #166 changes before it lands, they must survive there:

• the quoting character set;
• the five link forms spelled out;
• the list of unsupported Pandoc constructs;
• the table-limit numbers;
• the integrator interface list;
• the clipboard backend members.

Deliberately dropped, and known stale pointers

Dropped as obsolete:

• the "Status: bootstrap" label, and "the list under Known gaps is the work still to do" (planned work is the Roadmap now);
• the "Known gaps" heading;
• "There is currently no #if in the source": it was already untrue. The page now lists all five per-version sites.

Not changed, since ADRs are records: ADR 0009 and ADR 0027 say per-version differences are listed "in the README", and ADR 0025 cites "README, Keyboards". They now live in docs/reference/avalonia-versions.md and docs/reference/editing.md. Code comments, feature-inventory and manual-testing pointers were repointed.

The editor-integration roadmap line has no link: the plan (research report 21) is not in this repository, and ADR 0034 is only proposed.

AGENTS.md

The existing rules are kept. New rules cover:

• Headless.Run for tests that create controls;
• counted work, not wall-clock assertions;
• testing against a local liblcm with -p:SilLcmVersion (the refusal sweep tests are expected to fail);
• AotCheck needs vswhere (#164);
• Pandoc tests skip silently unless CI is set;
• every fwmd.* id needs a fixture case and a findings.md entry;
• format-doc examples are tested;
• the screenshot generator;
• Markdown and LCModel layering;
• merge only when every gh pr checks --json bucket bucket passes.

The per-version rule now points to docs/reference/avalonia-versions.md.

🤖 Generated with Claude Code