[pournasserian]

Closes #2564

What

This is the next F-API (#2425) slice. Each published entry gets a Markdown representation at a stable URL, and a site index lists every published entry for agents (API-03). The read endpoints it builds on merged as #2563.

• Core (FluentCMS.Core.Delivery):

  • EntryMarkdown.Render(item, url, entryUrl) writes front matter: the id, type and URL as quoted strings, and the version. Then come the title as the heading and every other field under its name. The fields follow the order of the definition that the published version was written against:

    • rich text as written, since it is stored as Markdown (SCH-02), inside a block quote. A quote is a container, so a fence, an HTML block or a list the rich text leaves open closes with its field;
    • other text through EntryMarkdown.Text, which escapes only what could open structure. Anywhere in the text, that is code, emphasis, links, autolinks, HTML and strikethrough, an underscore outside a word, an ampersand that starts an entity, and a trailing run of hashes. At the start of a line, it is a heading, list, quote, table or heading underline. Lines also lose their indentation. A value reads as written and can never pose as a heading, a field, a source or a link, while words and URLs keep their characters;
    • lists as bullets, each item keeping its own paragraphs and fences;
    • JSON in a fenced block;
    • whole-entry references as links to their Markdown, including references whose settings store "field": null;
    • entity-field references as the resolved published value;
    • media as the asset id;
    • on an entity, every fact, the title's included, followed by a **Source:** paragraph. Escaped text cannot form it, and quoted rich text cannot reach it. It says so when the fact is unsourced (ENT-02), and a source that is a web address is an autolink, so it stays exact.

    Unresolved references are listed with their reason.

  • EntryMarkdown.Title returns the first text field that holds text, on one line. EntryMarkdown.InlineText escapes a heading or link text.

  • IPublishedContent.IndexAsync() lists every published entry the caller may read, with its type and title, by type and then id.

  • PublishedItem carries its content type's name and the definition its version was written against (EntryVersions.ContentTypeVersion). A revision of the type waiting for review therefore changes nothing that readers see.

• Api:
  • GET /api/v1/entries/{id}.md returns text/markdown. A malformed id is a 400 problem, as for the JSON read.
  • GET /api/v1/index returns JSON with the id, type, version, title, URL and Markdown URL of each entry.
  • GET /api/v1/index.md and GET /llms.txt return the same index in Markdown, grouped by content type. Type names and titles are escaped.
  • The JSON items gain a markdown link.
• Docs: docs/api/delivery.md describes the Markdown form and the index.

Why

API-03 and the agent-first principle: an agent reads a site the way it reads any page, starting from /llms.txt. The Markdown URL is the entry's id, so it never changes across versions and always shows what is published. What an agent reads there must be faithful. Published text is content, never structure, so it cannot fake a field or a source.

Choices worth a look:

• The title is the first text field that holds text. In the reference model that gives a page its headline, a post its title and a product its name. Content types have no title field to name, and adding one would be a schema change.
• Escaping is targeted, not total, so GUIDs, URLs and identifiers stay readable in raw Markdown and links stay exact.
• Rich text is quoted. CommonMark has no other container that ends whatever the rich text opens, and the quote marks it clearly as the value.
• Media appears as its id until media has a delivery endpoint.
• The index loads every published document to read titles. That is fine at the thousands of entries M1 targets (D26).

Tests

• Unit:
  • A page renders exactly. The output includes front matter, a collapsed title, links, the resolved price, rich text, lists of text, references and rich text (multi-paragraph items and a fence), media, a boolean, an enum, a date and fenced JSON.
  • Text that tries to be a heading, a field, HTML, emphasis, an entity, an ordered or bullet list, an indented code block or a heading underline reads as text. A title ending in # keeps it.
  • On an entity, a rich text fact holding a fake **Source:** and an unclosed fence stays inside its quote. The real source of the fact and the next field follow unchanged.
  • An entity shows every fact with its source, the title fact included. A URL source is an autolink with its characters intact. A list fact's source stays out of the list.
  • URLs, words with underscores, C# and AT&T keep their characters, while emphasis, entities and a closing run of hashes are escaped.
  • The fallback heading escapes a type name holding a link, and unresolved references are listed.
  • Backslashes, brackets, autolinks and line breaks in link text stay text.
  • A backtick in JSON cannot close its fence.
• Integration, on SQLite and PostgreSQL:
  • A published page's Markdown shows its headline, its price resolved to 99 and a link to the product. After the second version is published, it shows the new headline and version 2 at the same URL.
  • After a type revision drops headline, the published page still reads against its own definition, and the index keeps its title.
  • An agent scoped to product gets only products from the index.
  • The index lists a published post, product and page once each, with titles, and leaves out a draft and a deleted page. After a second publish it shows version 2.
• HTTP:
  • The Markdown endpoint returns text/markdown with quoted front matter.
  • Unknown and malformed ids give problems.
  • The JSON and Markdown indexes match, with escaping, and /llms.txt equals index.md.

The full suite ran locally against a postgres:17 container as well as SQLite, and markdownlint is clean. There is no migration and no new package.

Review

A first independent review blocked this PR for three reasons:

• plain text was written as raw Markdown, so a value could fake a field, a source, HTML or a heading;
• rendering used the type's latest definition;
• index link text was only partly escaped.

All three are fixed above, along with its low findings:

• type names are escaped;
• the front matter is quoted;
• list items keep their blocks;
• unresolved references are listed.

A second review confirmed those fixes, fuzzing the escaping with Markdig, and found two more Medium problems:

• rich text went in verbatim, so an unclosed fence or HTML block could swallow later fields, and a rich text fact could show a fake source;
• the title fact's source was never written.

Both are fixed above, along with its Low findings:

• a list fact's source is no longer read as an extra list item;
• "field": null references now link;
• URLs keep their characters.

A third review gave MERGE. Its low findings are fixed: list items that start with blank lines now stay in their bullets, and the math and figure block openers of Markdown extensions are escaped at line start. Two Low findings are tracked as issues: whole-entry links to unpublished or deleted entries in #2593, and resolved references written with their own field type in #2602.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers