@heroiclands/package-build 24.1.1 → 25.1.0

package/docs/commands.md

@@ -2215,6 +2215,14 @@ dependencies; exact Item UUID validation remains part of compilation. Reads
 the content tree named by `root`, defaulting to
 `paths.content`; writes nothing.
 
+Every configured language note declares `data.roman`, its exact NFC Roman
+source characters. Lint checks language-tagged text before mapping, using the
+same inventory for a configured name and its BCP 47 tag. Visible linked labels
+are checked; destinations, attributes and verse structure are excluded. An
+explicit empty inventory declares no written characters. External tags without
+a language-note association retain their ordinary behavior. Standalone
+`package-build markdown` does not load these inventories.
+
 Name marking is advisory: lint checks explicit `.name` spans and authored link
 labels against the [name-marking
 conventions](authoring/links-and-markup.md#marking-names-in-prose). Plain prose
@@ -2575,14 +2583,11 @@ with visible text, nullable type/subtype and original source line/column.
 Local and dependency SQL schemas expose them through `names`; they travel in
 the metadata artifact.
 
-Metadata also includes each own note's spans, divs and verse fences marked with
-`lang=`, `font=` or `map=` under `runs`, with the language as written, the tag
-it resolves to, the font, the map and the original source line/column. Native
-runs carry `nativefont: true` in the metadata; language-only Roman runs omit
-the flag and do not receive script defaults. The `runs` SQL columns stay the
-same. Local
-and dependency SQL schemas expose them through `runs`, and each mapping note's
-rows through `maps`.
+Metadata includes each own note's spans, divs and verse fences marked with
+`lang=`, `font=` or `enc=` under `runs`, with the language as written, its
+resolved tag, font, encoding document Address and original source line/column.
+Roman runs use the default encoding and receive no inferred script face.
+Local and dependency SQL schemas expose these records through `runs`.
 
 The command prepares SQL tables, page lists, automatic sections and scalar
 expressions before publishing their prose targets. Each source uses its own
@@ -3151,173 +3156,167 @@ $ package-build reachability assets/content
 `package-build links [root]`, `package-build lint [root]`, [Diagnostics](diagnostics.md),
 [Configuration](configuration.md).
 
-### `package-build transliterate <map> [text..]`
+### `package-build encode [text..]`
 
 **NAME**
 
-Map a passage into a script exactly as the build maps a marked run.
+Encode roman text using an encoding document.
 
 **SYNOPSIS**
 
-```
-package-build transliterate <map> [--lang <language>] [--font <slug>] [--hex] [text..]
+```text
+package-build encode --enc <document|default> [--in|-i <file>] [--out|-o <file>] [text..]
 ```
 
 **DESCRIPTION**
 
-Reads the content index, as `package-build lint` does, and prints the passage
-rewritten by the mapping note whose `data.map.name` is `<map>`, through the
-same code the build sets a run marked `lang=<language> .nativefont map=<map> font=<slug>`
-with. With `--lang`, each word the language's lexicon states a native form for
-is written by it and every other word is spelled by the rows; without it, the
-rows alone apply. See
-[a map reads the dictionary first](reference/format-details.md#a-map-reads-the-dictionary-first).
-Under a [logographic map](reference/format-details.md#a-logographic-map) every
-word is written from the language's lexicon, by its own writing or its parts',
-and the rows write only the text between words.
-The text is the words given, joined by single spaces; `-` or no text reads it
-from standard input, less one trailing newline. Writes nothing.
+Reads an encoding document from the consuming package's content index and
+writes its Unicode output. `--enc` is an Address whose default type is `doc`,
+or `default` to keep text unchanged. The note supplies its font, and glyph
+codes come from that face's `fonts.json`. These commands apply the bare
+encoding; they do not apply a language's lexical native spellings.
 
-**OPTIONS**
+Give exactly one string argument, or `--in` with a UTF-8 file; `--in -` drains
+standard input. `--out` writes the exact result to a file. Standard output adds
+one newline only for string arguments; file and stream input add nothing.
+A refusal writes no result and preserves an existing output file.
 
-| Positional | Type             | Default | Description                            |
-| ---------- | ---------------- | ------- | -------------------------------------- |
-| `map`      | string           | —       | The `data.map.name` of a mapping note. |
-| `text`     | string, variadic | stdin   | The passage; `-` reads it from stdin.  |
+**OPTIONS**
 
-| Option   | Type    | Default                                                                           | Description                                                                                           |
-| -------- | ------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `--lang` | string  | —                                                                                 | A language declared in `languages`, whose lexicon is read first.                                      |
-| `--font` | string  | the language's face where the map is drawn in it, else the map's one face, if one | The face, whose own rows come first; required when neither gives one and the map lists more than one. |
-| `--hex`  | boolean | `false`                                                                           | Print the code points, as `U+XXXX` separated by spaces.                                               |
+| Option        | Description                                        |
+| ------------- | -------------------------------------------------- |
+| `--enc`       | Required encoding document Address, or `default`.  |
+| `--in`, `-i`  | Read a UTF-8 file, or standard input with `-`.     |
+| `--out`, `-o` | Write the exact result to a file.                  |
+| `[text..]`    | One quoted input string, used only without `--in`. |
 
 **EXIT STATUS**
 
-1 if the content index could not be built for any note, or the map, the
-language or the face names nothing, each reported as a finding: an unknown
-language at `languages` in the configuration, an unknown map or face at the
-content tree. 1, with the build's own message, if a capitalised word of the
-passage has a native form the rows cannot capitalise, or, under a logographic
-map, a word has no writing or stands for entries written differently.
-Otherwise 0.
+0 on success; 1 for unreadable files or an encoding refusal; 2 for a usage
+error. Findings go to standard error as `file:line:column: error: message`.
+Line and column count Unicode code points, starting at one. String input is
+named `<text>` and standard input `<stdin>`.
 
 **EXAMPLES**
 
-With Vylari's `zaron` stating a native form for `semaron`, and `lonak` stating
-none:
-
-```
-$ package-build transliterate semaron --lang vyl --hex zaron lonak
-U+F024F U+F0230 U+F023F U+F023C U+0020 U+F023A U+F023D U+F023C U+F0230 U+F0239
-$ package-build transliterate semaron --hex zaron
-U+F0255 U+F0230 U+F023F U+F023D U+F023C
-$ package-build transliterate semoran zaron
-assets/content: error: `semoran` is not a map: a map is named by the `data.map.name` of a mapping note; did you mean `semaron`?
+```sh
+package-build encode --enc vylsemaronenc "zaron"
+package-build encode --enc khelqalezuenc --in roman.txt --out native.txt
+package-build encode --enc khelzethuenc "⟦MAN⟧"
+printf 'zaron' | package-build encode --enc vylsemaronenc -i - -o native.txt
 ```
 
-The first run writes `zaron` by its exception; the second, with no `--lang`,
-spells it by the rows.
+**SEE ALSO**
+
+`package-build decode`, `package-build lexicon`, [Writing in invented scripts](guides/writing-in-invented-scripts.md#the-commands).
+
+### `package-build decode [text..]`
+
+**NAME**
+
+Decode Unicode through an encoding document.
 
-Under the logographic `zethu`, with Khelathi's `lekhunet` built from `lekhau`
-and the affix `-unet`, the plural written by its own sign, and `zamlu` given no
-writing:
+**SYNOPSIS**
 
+```text
+package-build decode --enc <document|default> [--in|-i <file>] [--out|-o <file>] [text..]
 ```
-$ package-build transliterate zethu --lang khel --hex lekhunet halziim.
-U+1EA93 U+1EBC7 U+0020 U+1EABB U+1EBE1 U+1EBED
-$ package-build transliterate zethu --lang khel zamlu
-error: `zamlu` has no `zethu` writing in the `khel` lexicon, and its parts do not give one; state one, or write the word directly in signs
+
+**DESCRIPTION**
+
+Reads the encoding's longest output rows back as roman text. `--enc` is
+required and resolves exactly as for `encode`. Literal spans decode to the
+encoding's own codes, or `U+XXXX` for an unnamed Unicode scalar. The bare
+command reads no language vocabulary; the [browser conversion API](api.md#browser-conversion)
+adds lexical recovery.
+
+**OPTIONS**
+
+| Option        | Description                                        |
+| ------------- | -------------------------------------------------- |
+| `--enc`       | Required encoding document Address, or `default`.  |
+| `--in`, `-i`  | Read a UTF-8 file, or standard input with `-`.     |
+| `--out`, `-o` | Write the exact result to a file.                  |
+| `[text..]`    | One quoted input string, used only without `--in`. |
+
+**EXIT STATUS**
+
+0 on success; 1 for unreadable files or a decoding refusal; 2 for a usage
+error. Diagnostics and output bytes follow the same rules as `encode`.
+
+**EXAMPLES**
+
+```sh
+package-build decode --enc vylsemaronenc --in native.txt --out roman.txt
+package-build decode --enc khelqalezuenc -i native.txt
+package-build decode --enc khelzethuenc --in signs.txt
 ```
 
 **SEE ALSO**
 
-`package-build lexicon <language>`, [Mapping notes](reference/format-details.md#mapping-notes).
+`package-build encode`, `package-build lexicon`, [Browser conversion](api.md#browser-conversion).
 
 ### `package-build lexicon <language>`
 
 **NAME**
 
-List a language's words with their native forms under a map.
+List a language's words and native writings under an encoding document.
 
 **SYNOPSIS**
 
 ```
-package-build lexicon <language> [--map <map>] [--font <slug>] [--derived] [--json]
+package-build lexicon <language> [--enc <encoding>] [--font <slug>] [--derived] [--json]
 ```
 
 **DESCRIPTION**
 
-Reads the content index and lists every word of the language note
-[`languages.<language>.note`](configuration.md#languages) names, in `data.words`
-order, each with its native form under `<map>`, or under the script the
-language note names in `data.writtenIn` when `--map` is left out: the stated exception where the
-word has one, else the rows' spelling, each exactly as
-`package-build transliterate` and the build give it. Each line holds, separated
-by tabs, the word's `form`, its native form, `exception` or `rows`, its `class`
-and its `gloss`. Writes nothing.
-
-Under a [logographic map](reference/format-details.md#a-logographic-map) the
-native form is the word's writing, and the third column says where it comes
-from: `own` for a writing the word states, `parts` for one its `built` pieces
-give, or `none`, with an empty second column, for a word with no writing. A
-word whose form a run cannot write, because the form stands for entries
-written differently or one of its parts does, is marked `ambiguous`, and its
-second column is still that entry's own writing: the signs to write directly
-for that sense. Every word listed with a writing and not `ambiguous` is written
-so by the build and by `package-build transliterate`.
-
-With `--derived`, the forms the language's own rules derive from those words
-follow them: each word's declared `variants`, then plurals, verb forms, replacing suffixes, agreeing forms and
-participles, exactly the regular forms
-[the mapped-run word check](authoring/links-and-markup.md#a-mapped-runs-words)
-accepts. Each is listed once, case folded as the check compares it, and spelled
-by the rows; a form that is itself a lexicon word is not repeated. Every line
-then has a sixth column: the lexicon word a derived form comes from, empty for
-the lexicon's own words. A derived line carries its word's `class` and `gloss`.
+Reads the content index and lists the words of the note named by
+[`languages.<language>.note`](configuration.md#languages), in authored order.
+`--enc` selects an encoding document; its language must agree with the
+requested language, and `--font`, when supplied, must equal its font.
+Native writings and composed parts take precedence over encoding mappings.
+
+Tab-separated output contains `form`, native text, source, class and gloss.
+Source is `own`, `parts`, `rows`, `none` or `ambiguous`. A missing writing leaves
+native text empty; an ambiguous entry shows that entry's own writing so the
+reader can choose signs for its meaning. JSON output preserves these fields
+and adds `ambiguous: true` where appropriate.
+
+With `--derived`, declared variants and regular forms follow the citations,
+each once. The final tab-separated column, or JSON `from`, names its source
+word. This lists the forms the language's authored grammar supplies; it does
+not infer grammatical roles from an unlabelled variant.
 
 **OPTIONS**
 
-| Positional | Type   | Default | Description                                         |
-| ---------- | ------ | ------- | --------------------------------------------------- |
-| `language` | string | —       | A declared language whose `note` names its lexicon. |
+| Positional | Type   | Default | Description                                           |
+| ---------- | ------ | ------- | ----------------------------------------------------- |
+| `language` | string | —       | A configured language whose `note` names its lexicon. |
 
-| Option      | Type    | Default                                                                           | Description                                                                                                                                                                                                                                      |
-| ----------- | ------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `--map`     | string  | the language's `data.writtenIn` map                                               | The `data.map.name` of a mapping note; required when the language note states no `data.writtenIn`.                                                                                                                                               |
-| `--font`    | string  | the language's face where the map is drawn in it, else the map's one face, if one | The face; required when neither gives one and the map lists more than one.                                                                                                                                                                       |
-| `--derived` | boolean | `false`                                                                           | Also list the forms the language's rules derive, each with the word it comes from.                                                                                                                                                               |
-| `--json`    | boolean | `false`                                                                           | Print a JSON array of `{ form, native, exception, class, gloss }` instead; a derived form adds `from`. Under a logographic map `source` (`own`, `parts` or `none`) takes the place of `exception`, and an ambiguous word adds `ambiguous: true`. |
+| Option      | Type    | Default                  | Description                                                |
+| ----------- | ------- | ------------------------ | ---------------------------------------------------------- |
+| `--enc`     | string  | required                 | An encoding document Address.                              |
+| `--font`    | string  | encoding document's font | A face supported by the encoding.                          |
+| `--derived` | boolean | `false`                  | Include variants and derived forms with their source word. |
+| `--json`    | boolean | `false`                  | Print JSON records instead of tab-separated lines.         |
 
 **EXIT STATUS**
 
-1 if the content index could not be built for any note, or the language, the
-map or the face names nothing, no map is named and the language note states no
-`data.writtenIn`, the language states no `note`, or a capitalised
-word has a native form the rows cannot capitalise, each reported as a finding.
-Otherwise 0.
+0 on success; 1 for content-index findings, an unknown language, encoding or
+face, a missing language note or encoding selection, or an invalid conversion.
 
 **EXAMPLES**
 
 ```
-$ package-build lexicon vyl --map semaron | head -3
-zaron	<native form>	exception	n	an oath
-lonak	<native form>	rows	n	a road
-thizaron	<native form>	rows	n	a seal
-$ package-build lexicon vyl --map semaron --derived | grep -P '\talathos$'
-alatha	<native form>	rows	pron	he, that one	alathos
-alathon	<native form>	rows	pron	he, that one	alathos
-alathoi	<native form>	rows	pron	he, that one	alathos
-alathai	<native form>	rows	pron	he, that one	alathos
-$ package-build lexicon khel --map zethu | grep -P '\t(none|ambiguous)\t'
-nelgir	<writing>	ambiguous	n	a god
-Nelgir	<writing>	ambiguous	stem	god
-zamlu		none	n	music
+package-build lexicon vyl --enc vylsemaronenc
+package-build lexicon vyl --enc vylsemaronenc --derived --json
+package-build lexicon khel --enc khelzethuenc
 ```
 
 **SEE ALSO**
 
-`package-build transliterate <map> [text..]`,
-[A language's words](reference/format-details.md#a-languages-words).
+`package-build encode`, `package-build decode`,
+[native spellings and parts](reference/format-details.md#native-spellings-and-parts).
 
 ### `package-build core`
 

package/docs/configuration.md

@@ -734,7 +734,7 @@ any finding it reports is a refusal, joined into one message:
 The languages a note may tag text with, by short name. A note writes the short
 name, as in `[Daimela, helthos.]{lang=vyl}`; the build gives the text the
 language's tag. See
-[marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
+[marking language, font and encoding](authoring/links-and-markup.md#marking-language-font-and-encoding).
 
 ```yaml
 languages:
@@ -761,20 +761,18 @@ checked.
 **`note`** names the language note whose `data.words` is the language's
 lexicon, as an Address in this package: `skill-vylarilng`, or the bare
 shortcode, whose type defaults to `skill`. A run marked with the language and a
-`map=` writes each word the lexicon states a native form for by that form, and
+`enc=` writes each word the lexicon states a native form for by that form, and
 spells every other word by the map's rows; see
-[a map reads the dictionary first](reference/format-details.md#a-map-reads-the-dictionary-first).
+[an encoding reads the dictionary first](reference/format-details.md#an-encoding-reads-the-dictionary-first).
 Language word-book validation applies to Roman and native runs alike,
-independently of `.nativefont` or mapping: every word is a word of the lexicon, of a name the language note's
+independently of encoding selection: every word is a word of the lexicon, of a name the language note's
 own register lists, or a regular form of a lexicon word, and any other word is an error; see
-[a mapped run's words](authoring/links-and-markup.md#a-mapped-runs-words).
-The language note may also name the script the language is written in, as
-`data.writtenIn: { map, font }`, and a run explicitly marked with both the language and `.nativefont` is
-then mapped and set in it. Language-only runs retain authored Roman spelling
-and the surrounding prose font. Native `map=` and `font=` override the
-configured halves independently; missing halves require explicit overrides; see
-[a language's script](authoring/links-and-markup.md#a-languages-script). The
-script belongs to the language note, and the configuration never states it.
+[a mapped run's words](authoring/links-and-markup.md#an-encoded-runs-words).
+An encoding document names its configured language in `data.language` and
+its installed face in `data.font`. `enc=` selects that document and infers
+those values; explicit choices must agree. A run without an encoding uses
+`enc=default` and keeps its Roman spelling. See
+[marking language, font and encoding](authoring/links-and-markup.md#marking-language-font-and-encoding).
 A language with no `note` tags its text and has no lexicon. Whether the note
 resolves is checked by `package-build lint`, at the key:
 
@@ -1905,6 +1903,7 @@ packageBuild:
 | [`packageBuild.baseStyles`](#packagebuildbasestyles)                                       | boolean                                     | no       | `true`                                                     |
 | [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
 | [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.converterData`](#packagebuildconverterdata)                                 | string (stage-relative JSON path)           | no       | `null`                                                     |
 | [`packageBuild.schema`](#packagebuildschema)                                               | object (`{documentType: {from, registry}}`) | no       | `[]`                                                       |
 | [`packageBuild.clean`](#packagebuildclean)                                                 | object                                      | no       | `{extra: []}`                                              |
 | [`packageBuild.lang`](#packagebuildlang)                                                   | object                                      | no       | see below                                                  |
@@ -1916,7 +1915,7 @@ packageBuild:
 | [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
 | [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
 
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, shippingLicenses, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, shippingLicenses, baseStyles, manifest, manifestFlags, converterData, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
@@ -2338,3 +2337,22 @@ the source directory:
 | `packageBuild.manifest.id`, `.version`, `.description`, `.url`, `.bugs`, `.manifest`, `.download`, `.compatibility`, `.relationships`, `.packs` | Forbidden — each is derived from `package.json` or the top level of `package-build.config.yaml`; see [`packageBuild.manifest`](#packagebuildmanifest). |
 | `publish.site` (any value)                                                                                                                      | Refused — publication follows the authored content tree.                                                                                               |
 | `packs`, `itemBuilders`, `docs`, `compatibility`, `relationships`, `systems`, `requiresSystem`, `stats`, `foundryPackage`                       | Forbidden in a `documentation` package — each describes a Foundry package this kind is not; see the key's own section for its located refusal message. |
+
+### `packageBuild.converterData`
+
+Optional path for a browser converter's JSON data, relative to
+`packageBuild.stageDir`. `package-build manifest` writes it during the module
+build from the same published encodings and language vocabulary that render
+native text. The path must stay within the stage, end in `.json`, and name an
+artifact other than `module.json`, `system.json` or `package.json`. Absolute
+paths and parent traversal are refused. Omission writes no converter file.
+
+```yaml
+packageBuild:
+  converterData: data/converter.json
+```
+
+The result is `build/stage/data/converter.json` with the default stage. It
+ships with that stage in the release archive. See the
+[data format](reference/format-details.md#converter-data-format) and
+[browser API](api.md#browser-conversion).

package/docs/content-format.md

@@ -31,10 +31,17 @@ Leading `:` captions describe the next supported block; `:@` captions also numbe
 
 A code fence with language `verse` keeps verse lines, stanza breaks and relative indentation. Leading periods set indent levels and are removed from the text; leading spaces do not count. Blank lines separate verse units and `***` separates stanzas. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [verse](authoring/links-and-markup.md#verse), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans). `numstep=N` numbers every Nth line. `cols=N` sets a positive whole number of columns and defaults to one. With `cols` above one, each content line starts with an integer and one or more spaces; numbers lie in `1..cols` and are nondecreasing within each blank-separated logical row. Any column may be omitted and keeps an empty cell. A column may repeat without limit: its first reading is foreground and its later readings are grey, independently for every column and row. Number prefixes are not displayed; `numstep` counts logical rows. `***` separates stanzas. Inline language and native presentation are explicit on each authored run. See [verse in columns](authoring/links-and-markup.md#verse-in-columns).
 
-A code fence with language `scroll` sets text in a script whose script note states `direction: vertical-rl` as columns, top to bottom, read from the right. The lines of a paragraph are joined, and each paragraph starts a fresh column. `rows=N` is the characters in a column and `cols=M` the columns in a panel, each a whole number above zero; `lang=`, `font=` and `map=` mark the text as on a verse fence, and `.nativefont` requires an explicit language and a font supplied by a language default or an override; mapping is optional when no default supplies it. The site, the preview and Foundry set it with `writing-mode: vertical-rl` in a panel that scrolls sideways from the right; the book draws its panels as images from the face's outlines, each with its roman text as alt text. A scroll fence in a script written in lines is an error. See [scrolls](authoring/links-and-markup.md#scrolls).
-
-A span, a generic div, a verse fence or a scroll fence identifies its language with `lang=` and keeps its authored spelling and the surrounding prose font. Explicit `.nativefont` on that same construct, with its own explicit `lang=`, requests the language's configured `data.writtenIn` map and font; `map=` and `font=` override their halves independently. A missing font default requires `font=` rather than inference; mapping is optional when the language supplies none. Native font or map keys require `.nativefont`; Roman `font=mono`, `serif` and `sans` remain available independently. Unmarked text follows its passage, while a marked language-only child stays Roman, even in the same language as a native parent. Standalone wikilinks make the same choice: `[[address|Name]]{lang=vyl}` stays Roman and `[[address|Name]]{lang=vyl .nativefont}` uses native presentation without changing its destination or presentation cues. `font=` is a face of the installed `@heroiclands/fonts`, named by its class without `hl-`, or `mono`, `serif` or `sans`. `map=` names a mapping note: a `doc` note whose `data.map` lists the fonts it is drawn in and rows that rewrite the text before it is set, a font's own rows first. With `lang=` naming a language whose configured `note` names its language note, a word whose entry states a `native` form for the map is written by it, and the rows spell every other word. A map stating `logographic: true` spells no word by its rows: each word is written by its own `native` entry or its parts' writings, and a word with neither, or whose form stands for entries written differently, is a located error. Language word-book validation applies to Roman and native runs alike,
-independently of `.nativefont` or mapping: every word is a lexicon form, a word of a name the language note's own register lists under a tongue other than `translation`, or a form a plural row, the verb pattern or an affix stating `replaces` derives from a lexicon form, and any other word is an error at the word. A character a face does not draw, after the map, is an error at the character it came from. A verse fence that states `scan=` (the `name` of a `data.metres` entry of a `doc` note) with a `lang=` whose language note states `data.sounds.stress` is counted line by line by the beat convention, and a line that cannot have the metre's beats is a warning at the line; see [metres](authoring/links-and-markup.md#metre). Text with a font, a map or a declared language is plain, except that text set in a face takes `*…*` and `**…**`: they render by the convention its language note's `data.emphasis` states, else the one the script note listing its face states in `data.script` (`rubric` or `overline`), else plainly. Actual bold or italic markup inside a span whose effective language is not English is an error, whether that language is declared or inherited and whether or not the text uses a font; English text remains eligible. Every marked construct is a row of the `runs` relation, every mapping row of the `maps` relation, and every native form of the `natives` relation. See [marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
+A code fence with language `scroll` sets text in a script whose script note states `direction: vertical-rl` as columns, top to bottom, read from the right. The lines of a paragraph are joined, and each paragraph starts a fresh column. `rows=N` is the characters in a column and `cols=M` the columns in a panel, each a whole number above zero; `lang=`, `font=` and `enc=` mark the text as on a verse fence, an explicit `enc=` selects an encoding document and its language and font. The site, the preview and Foundry set it with `writing-mode: vertical-rl` in a panel that scrolls sideways from the right; the book draws its panels as images from the face's outlines, each with its roman text as alt text. A scroll fence in a script written in lines is an error. See [scrolls](authoring/links-and-markup.md#scrolls).
+
+A span, generic div, verse or scroll fence uses `enc=default` unless it selects
+an encoding document. `enc=` is an Address whose default type is `doc`; the
+document names its language and font, and explicit `lang=` or `font=` values
+must agree. Each encoding tries authored native writings, complete parts and
+then its mappings. Unknown characters, undefined glyph codes and conflicting
+selections are located errors. `⟦…⟧` reads the selected font's glyph codes or
+strict Unicode scalars. See [encodings](reference/format-details.md#encodings).
+Language word-book validation applies to both Roman and native runs. Parallel
+verse retains independent authored readings and their column numbers.
 
 Mark a name without a note as `[Name]{.name data-type="being"}`; the optional
 classification uses the declared note vocabulary. The [name-marking

package/docs/diagnostics.md

@@ -303,26 +303,25 @@ For example, `[a *word*]{lang=vyl}` locates the finding at the `*` that opens
 the emphasis. A font does not make the markup valid; the language rule applies
 to the span whether its text uses a script face or ordinary type.
 
-## Native presentation is explicit
-
-A language-only run keeps its authored spelling and prose font. Native
-presentation requires `.nativefont` and an explicit `lang=` on that same
-span, div, verse fence or scroll fence. An inherited language does not satisfy
-this requirement. Findings point to the authored class or override:
+Use `[word]{.emph}` for emphasis in a non-English span. It inherits the
+surrounding run's language, face and encoding. These findings point to the
+opening `[` of the emphasis span:
 
 ```text
-`.nativefont` requires an explicit `lang=` on the same construct
-native `font=semaron-kuriale` requires `.nativefont` and an explicit `lang=` on the same construct
-`map=semaron` requires `.nativefont` and an explicit `lang=` on the same construct
-`.nativefont` has no default `font=` for `vyl`; state `font=` explicitly
+a span in non-English language `vyl` holds no `.strong` emphasis
+`vyl` marks emphasis with a word, not a mark; write the word
+a span takes `.emph` or `.strong`, not both
 ```
 
-A missing font needs an explicit `font=` or a language font default. Mapping is
-optional when the language supplies none; configured maps still apply to
-native runs unless explicitly overridden. `font=serif`, `sans` and `mono`
-remain independent Roman choices. Each authored reading makes its own presentation choice in parallel verse,
-for example `1 [Zaron]{lang=vyl .nativefont}` and
-`3 [Zaron]{lang=vyl}` inside a `cols=3` poem. The Roman repeat stays Roman.
+## Native presentation is explicit
+
+`enc=` resolves an encoding document and infers its language and font.
+`enc=default` leaves Roman text unchanged. A conflicting explicit language or
+font is a finding at that attribute. Encoding-note schema errors point to
+frontmatter; missing, duplicate or malformed font glyph codes point to
+`fonts.json`. Their original source positions survive preview, lint, site,
+Foundry and book builds. Text diagnostics use code-point columns; run offsets
+and captured index coordinates retain UTF-16 units.
 
 ## Summary counts and prose are not findings
 
@@ -510,3 +509,31 @@ and exits `1`, because it saw two `error`-severity diagnostics. The summary
 line the emitting process printed to stdout, `3 finding(s) across 1
 note(s).`, never reaches the parser at all — it was never on stderr, and the
 regex would not have matched it if it had been.
+
+## Standard Roman punctuation
+
+Each configured language's `data.roman` adds its own characters to the shared
+Roman standard. Listing standard punctuation or literal boundaries in that
+field is an error at the field. Quote pairs balance and alternate; an English
+double quotation mark, `<<`, `>>` or three periods receives an error at the
+source mark. A terminal is optional, and authored capitalization is preserved.
+
+A semicolon or colon needs a comma for a pause or a period between complete
+sentences. An interruption or abandoning ellipsis within a run needs an
+immediate terminal; at the end of the run it may stand alone. A closing
+quotation is not an outer-sentence terminal.
+
+A native character pasted directly into a configured language run receives a
+finding naming its `⟦U+XXXX⟧` spelling. Use that notation, or the chosen
+encoding's codage name, inside the literal markers. The encoder checks the
+codes; the Roman validator leaves their contents immutable.
+
+A verse fence uses its authored line endings for boundaries. A literal `/`
+inside it is an error at that slash. Visual indentation does not add periods
+to the encoded text. Source positions survive Markdown escapes and nested
+`.emph` or `.name` spans.
+
+Language-run diagnostic columns count Unicode code points, so a supplementary
+character occupies one column. Source offsets and the SQL `runs.column` field
+use UTF-16 units for source indexing. An encoding-file finding retains that
+file's own location; a note's frontmatter offset is not added to it.