diff --git a/AGENTS.md b/AGENTS.md index f9b971d..eaad46f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ In `docs/decisions.md`: - Unknown nodes ride the carry - The carry fence names the node type - A code block is a fence per text node -- Foreign HTML sorts three ways +- Foreign HTML reads best effort and is never refused - Names stay text - Directives under `!adf:` - CommonMark is a subset @@ -94,7 +94,7 @@ In `docs/decisions.md`: - The real-world corpus holds anonymized documents from sites whose licence it records - The feature table is a section per corpus example, led by a summary table - Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented -- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead +- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content - `htmlToAdf` reads any HTML, with no option and no second call ## 1. Nothing about any consumer in the library diff --git a/README.md b/README.md index d40811b..436dcdf 100644 --- a/README.md +++ b/README.md @@ -286,9 +286,9 @@ which is free text. - **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back. Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit. -Behind those apps, the people who read and write the markdown and the HTML: product -managers, engineers and support agents working in Atlassian products through a plugin or another -UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. +Behind those apps, the people who read and write the markdown, the HTML and the Jira wiki markup: +product managers, engineers and support agents working in Atlassian products through a plugin or +another UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. Also behind them, the people who read a document's plain text as they read an email, whether it arrives in an email, a notification or a search hit. They see no markup, and rely on text that diff --git a/docs/decisions.md b/docs/decisions.md index 7a14dc2..2edd175 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -161,25 +161,23 @@ node, so each node keeps its own text. The fences carry one info string, since A language, and none is empty beside another, since a text node holds text. The grammar: `spec/flavour.md` §The CommonMark blocks, the `codeBlock` bullet. -## Foreign HTML sorts three ways +## Foreign HTML reads best effort and is never refused -2026-08-23, the sort 2026-09-20, the maintainer. Goals 1 and 5. Valid while ADF holds no node -for a bare container, a comment or a script. Lands with `todo.md` item 137. +2026-08-23, the sort 2026-09-20, best effort 2026-11-15, the maintainer. Goals 7 and 12. Valid while +ADF holds no node for a bare container, a comment or a script. Lands with `todo.md` item 137. -Every foreign element `htmlToAdf` and the markdown readers read sorts one of three ways, never a -silent drop of content: +HTML from emails, CMSs and editors guarantees nothing, so no foreign element is refused. Each reads +one of two ways: - A container around document content that ADF has no node for unwraps to its children, its own attributes dropped: `