feat: rewrite docs

docs/glossary.md

@@ -1,118 +1,158 @@
 # Glossary
 
+A scientific paper changes after it is published: errata appear, readings get corrected, annotations pile up. manuspec is a set of file formats for scientific papers that keeps each sentence findable through those changes (repository: <https://git.scient.ing/infra/manuspec>).
+This glossary defines its terms for readers from newcomer to expert, implementers included.
+Each entry gives the plain meaning, then the precise one, then the chapter that defines it.
+
+A hash is a fixed-length fingerprint of data; changing one character changes it.
+SHA-256 is the hash function the formats use.
+The specification is at version 0.1.0, and each format is `candidate` or `provisional` in `registry/formats.json`.
+Format names begin with `scienting-`, as in `scienting-doc/1`; that prefix is the formats' namespace, a separate matter from the repository's name. "Outside term" marks a standard from another project.
+
 Address
-:   A string naming a node, optionally pinned to a hash and narrowed to a span: `key#id@hash6[start:end]`.
+:   A string that names one node, optionally pinned to its state by the first six digits of its `node_hash` and narrowed to a span of code points (numbered characters of text): `key#id@hash6[start:end]`. ([6.1](../spec/06-anchors.md#61-addresses))
 
 Alias
-:   A legacy ID kept so that old references still lead to the node that now holds their text.
+:   A legacy ID kept so that old references still lead to the node that now holds their text. ([4.3](../spec/04-identity.md#43-permanence-retirement-and-aliases))
 
 Align key
-:   A hash of a node's lossy projection, used only to propose that two readings hold the same sentence.
+:   A hash of a node's lossy projection, used only to propose that two readings hold the same sentence; it never certifies anything. ([5.1](../spec/05-hashes.md#51-the-five-values))
 
 Anchor
-:   The stored form of a pinned address, with its quotation and context, that resolves as current, changed below, moved, reattached or stale.
+:   The stored form of a pinned address, with its quotation and context, so that a reference can be found again after the text changes.
+It resolves as current, changed below, moved, reattached or stale. ([6.2](../spec/06-anchors.md#62-the-anchor), [6.5](../spec/06-anchors.md#65-resolution))
 
 Asset store
-:   Where a team keeps files by SHA-256: witnesses, images, crops and withheld text.
+:   Where a team keeps files by SHA-256: witnesses, images, crops and withheld text. ([12.6](../spec/12-package.md#126-assets))
 
 Bundle
-:   One SQLite file with every table and a full-text index, which readers, servers and MCP servers query.
+:   One SQLite file with every table and a full-text index, which a reader or a store queries.
+Format `scienting-bundle/1`, `provisional`. ([13.5](../spec/13-database.md#135-the-bundle))
 
 Changed below
-:   The resolution of an anchor on a container that is unchanged in itself while something inside it changed.
+:   The resolution of an anchor on a container that is unchanged in itself while something inside it changed. ([6.5](../spec/06-anchors.md#65-resolution))
 
 Correction
-:   An operation on an established document, with its evidence and author; never edited, only appended.
+:   An operation on an established document, with its evidence and author; never edited, only appended. ([11](../spec/11-corrections.md))
 
 Document
-:   The text established for one version of one work, as a tree of nodes.
+:   The text established for one version of one work, from one or more witnesses, as a tree of nodes. ([2.1](../spec/02-model.md#21-four-objects), [3](../spec/03-nodes.md))
 
 Drift
-:   How much has changed below a container since an anchor on it was made, counted from the corrections.
+:   The amount that has changed below a container since an anchor on it was made, counted from the corrections: the share of the container's leaves touched by later corrections.
+It is reported as `none`, `low` or `high`, with a default threshold of a quarter. ([6.6](../spec/06-anchors.md#66-drift))
 
 Exercise
-:   An annotation whose body holds a prompt, an answer key of anchors or a value, and a grading rule.
+:   An annotation whose body holds a prompt, an answer key and a grading rule.
+The key is anchors, a verdict, a chain, a value or planted errors, by exercise kind. ([19.1](../spec/19-exercises.md#191-exercises))
 
 Fidelity level
-:   How far a leaf's text was checked against its source, from F0 converted to F3 proofread.
+:   How far a leaf's text was checked against its source, from F0 converted to F3 proofread. ([8.1](../spec/08-fidelity.md#81-levels-of-fidelity))
+
+JATS
+:   Outside term.
+Journal Article Tag Suite, ANSI/NISO Z39.96-2024, an XML format in which publishers and archives exchange journal content ([the NISO page](https://www.niso.org/publications/z3996-2024-jats)).
+In manuspec, `jats` is a witness kind: the fixture `okafor2025open` was established from a JATS file and a PDF that agree.
+The formats ingest JATS and do not replace it. ([2.3](../spec/02-model.md#23-witnessesjson))
 
 Keyed hash
-:   A content value computed as an HMAC under a team key or a key derived from page fingerprints, so a short text cannot be recovered by hashing guesses.
+:   A content value computed as an HMAC (a hash mixed with a secret key) under a team key or a key derived from page fingerprints, so a short text cannot be recovered by hashing guesses. ([5.8](../spec/05-hashes.md#58-keyed-hashes))
 
 Layer
-:   A named set of annotations with one purpose, audience, visibility and license.
+:   A named set of annotations with one purpose, audience, visibility and license. ([18.2](../spec/18-layers.md#182-the-layer))
 
 Leaf
-:   A node that holds text itself: a sentence, cell, reference, author line, keyword line, equation, equation line, code or algorithm.
+:   A node that holds text itself: a sentence, cell, reference, author line, keyword line, equation, equation line, code or algorithm [CHECK: spec/03 §3.6 says an `equation-line` is never a text leaf, while spec/06 §6.4 lists it as a leaf anchor kind; confirm the intended list]. ([3.6](../spec/03-nodes.md#36-the-plain-projection))
 
 Lossy projection
-:   A node's text with scripts flattened, citation marks, whitespace and dashes removed, and case folded; used for proposing alignments.
+:   A node's text with scripts flattened, citation marks, whitespace and dashes removed, and case folded; used for proposing alignments. ([5.5](../spec/05-hashes.md#55-the-lossy-projection))
 
 Match hash
-:   A hash of a node's strict projection; equal match hashes are what corroboration requires.
+:   A hash of a node's strict projection.
+Two readings agree only when their match hashes are equal and their complex-notation keys are equal.
+A complex-notation key is `notation:source` for a piece of math too complex for the formats to normalize, with the source's whitespace removed ([5.3](../spec/05-hashes.md#53-the-strict-projection)). ([5.1](../spec/05-hashes.md#51-the-five-values), [5.3](../spec/05-hashes.md#53-the-strict-projection))
 
 Node
 :   An addressable part of a document: a section, paragraph, sentence, figure, panel, caption, table, row, cell, equation, footnote, reference and the rest.
+Each node has a permanent ID and five content values; table columns and figure-text items have IDs and are not nodes. ([3](../spec/03-nodes.md), [4.2](../spec/04-identity.md#42-minting-node-ids))
 
 Own hash
-:   A hash of a node's own content without its children, used to judge anchors on containers.
+:   A hash of a node's own content without its children, used to judge anchors on containers that have content of their own.
+The `node_hash` is a hash of the own hash and the children's node hashes. ([5.1](../spec/05-hashes.md#51-the-five-values), [5.2](../spec/05-hashes.md#52-own-content))
 
 Package
-:   A document as a folder of canonical JSON files with a manifest whose hash pins them all.
+:   A document as a folder, or a zip of one, of canonical JSON (a plain-text data format) and JSON Lines (one JSON value per line) files, with a manifest whose hash pins them all. ([12](../spec/12-package.md))
 
 Page fingerprint
-:   A hash of a page's size, its text with download stamps removed, and its images, so that differently stamped downloads share their pages.
+:   A hash of a page's size, its text with download stamps removed, and its images, so that differently stamped downloads share their pages. ([7.1](../spec/07-geometry.md#71-page-fingerprints))
 
 Plain projection
-:   A node's text as one string, on which offsets, quotations and text hashes are defined.
+:   A node's text as one string, on which offsets, quotations and text hashes are defined. ([3.6](../spec/03-nodes.md#36-the-plain-projection))
 
 Policy
 :   A project owner's signed decision that settles rights a record leaves unknown.
+It never overrides a use the record sets to true or false. ([14.2](../spec/14-rights.md#142-effective-uses))
 
 Project
 :   A team's curated set of documents, with its members, layers, data, reading paths and drafts.
+Format `scienting-project/1`, `provisional`. ([20](../spec/20-projects.md))
 
 Receipt
-:   One signature over a Merkle root of what a person reviewed in a sitting, which sets the level of what it lists.
+:   One signature over a Merkle root of what a person reviewed in a sitting.
+The signature sets the fidelity level of what it lists.
+A Merkle root is a single hash that commits to a list of items; receipts build it as RFC 6962 (an internet standards document) describes, a tree that [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162) obsoletes and defines identically. ([8.3](../spec/08-fidelity.md#83-receipts), [8.5](../spec/08-fidelity.md#85-merkle-roots))
 
 Revision
-:   The index of the last correction applied to a document; anchors and receipts record it.
+:   The index of the last correction applied to a document, or 0 when there is none; anchors and receipts record it. ([11](../spec/11-corrections.md))
 
 Revocation
-:   A signed record that withdraws a receipt, or every receipt by one signer in a period.
+:   A signed record that withdraws a receipt, or every receipt by one signer in a period. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))
 
 Rights record
-:   A witness's license, the basis on which the team holds it, and the uses that basis allows.
+:   A witness's license, the basis on which the team holds it, and the uses that basis allows. ([14.1](../spec/14-rights.md#141-the-rights-record))
 
 Roster
-:   The list of keys that may sign, with their owners and purposes.
+:   The list of keys that may sign, with their owners and purposes. ([8.7](../spec/08-fidelity.md#87-revocations-and-the-roster))
+
+Selector
+:   Outside term.
+In the W3C Web Annotation Data Model, the part of an annotation's target that says where in the source resource the annotation applies.
+The model defines `TextQuoteSelector` (exact text, with optional prefix and suffix) and `TextPositionSelector` (offsets, which the model calls very brittle), among others ([the W3C model](https://www.w3.org/TR/annotation-model/)).
+Layers use a custom `AnchorSelector`, which carries an anchor, followed by a `TextQuoteSelector` for tools that do not know it; they use neither `TextPositionSelector` nor `FragmentSelector`. ([18.3](../spec/18-layers.md#183-the-annotation))
 
 Spot-check
-:   A second reviewer's check of a sample of a receipt's nodes, drawn from a seed nobody can steer.
+:   A second reviewer's check of a sample of a receipt's nodes, drawn from a seed nobody can steer: the checker's deterministic signature over the receipt's record hash. ([8.8](../spec/08-fidelity.md#88-spot-checks))
 
 Stamp rule
-:   A pattern that recognizes a publisher's download stamp in a page's text, so that fingerprints ignore it.
+:   A pattern that recognizes a publisher's download stamp in a page's text, so that fingerprints ignore it. ([7.2](../spec/07-geometry.md#72-stamp-rules))
 
 Strict projection
-:   A node's text with notation folded to one canonical form and structure kept; used for certifying agreement.
+:   A node's text with notation folded to one canonical form and structure kept; used for certifying agreement. ([5.3](../spec/05-hashes.md#53-the-strict-projection))
 
 Suspect
-:   A doubtful reading raised for a person or a review session to answer.
+:   A doubtful reading raised for a person or a review session to answer. ([5.7](../spec/05-hashes.md#57-suspects))
 
 Targeted F3
 :   Proofreading the nodes a team's claims, quotations and datasets rest on, rather than every node.
+The target set also includes every display equation and, under the project's digit rule (`all`, `anchored-sections` or `none`), sentences with a digit in a text or math run (an inline stretch of plain text, or of TeX or Typst math, within the sentence; [3.5](../spec/03-nodes.md#35-inline-runs)). ([8.10](../spec/08-fidelity.md#810-targeted-f3))
 
 Text policy
-:   Whether a package carries its text (`full`) or withholds it (`checks-only`).
+:   Whether a package carries its text (`full`) or withholds it (`checks-only`). ([12.5](../spec/12-package.md#125-text-policies))
 
 Verdict
-:   A judgment of whether a cited passage supports a citing sentence: supports, partly, does not, or cannot tell.
+:   A judgment of whether a cited passage supports a citing sentence: supports, partly, does not, or cannot tell. ([19.2](../spec/19-exercises.md#192-verdicts))
 
 Version
-:   One expression of a work: a preprint, the version of record, an erratum, the Supporting Information.
+:   One expression of a work: a preprint, the version of record, an erratum, the Supporting Information. ([2.1](../spec/02-model.md#21-four-objects))
+
+Web Annotation
+:   Outside term.
+The W3C Recommendation of 23 February 2017 for annotations with a body, a target and a motivation ([the W3C model](https://www.w3.org/TR/annotation-model/)).
+It gives sentences no permanent IDs and reports no outcomes such as current or stale; for annotation in general, it and its clients are the better choice.
+Layers are Web Annotations. ([18](../spec/18-layers.md))
 
 Witness
-:   One file of one version of a work, identified by its SHA-256.
+:   One file of one version of a work, identified by its SHA-256. ([2.1](../spec/02-model.md#21-four-objects), [2.3](../spec/02-model.md#23-witnessesjson))
 
 Work
-:   A piece of scholarship across all its versions.
+:   A piece of scholarship across all its versions. ([2.1](../spec/02-model.md#21-four-objects))