feat: rewrite docs

context/README.md

@@ -1,14 +1,126 @@
 # JSON-LD context
 
-`scienting-1.jsonld` is the context that, together with the W3C Web Annotation context, makes every annotation layer valid JSON-LD.
-It is published at `https://scient.ing/ns/scienting/1.jsonld`, and every layer and annotation lists both:
+Three readers use this page.
+A newcomer, such as a student who has not met these formats, can read it from the top.
+Each term is defined where it first appears, and the example comes from the fixtures.
+An implementer who is writing a reader, writer, converter or checker will find the exact behavior, the defining chapter, the files that pin it, and the traps in "Using the context".
+An expert who knows the neighboring standards will find the status of the formats and a short comparison in "Status and comparison".
+
+## What the context is
+
+Annotations are notes attached to a passage of a paper, such as a plain-language explanation of a term or a question for a study group.
+Annotation layers store them as JSON, a text format for structured data, one annotation per line.
+A shared standard, the [World Wide Web Consortium (W3C) Web Annotation Data Model](https://www.w3.org/TR/annotation-model/), says what an annotation contains: a body (the note), a target (what it is about) and a selector (how to find the passage inside the target).
+
+JSON-LD is JSON plus a rule that gives every field name a global meaning, written as an IRI (an identifier shaped like a web address).
+The rule lives in a context, a file that maps short field names to IRIs.
+Two tools that read the same context agree on what `target` or `status` means, even if they know nothing else about each other.
+
+`scienting-1.jsonld` is the context that makes every annotation layer valid JSON-LD, together with the W3C Web Annotation context.
+The Web Annotation context supplies `Annotation`, `body`, `target` and `selector`.
+This one supplies the terms the formats add.
+It is published at `https://scient.ing/ns/scienting/1.jsonld` [CHECK: the comparison source could not fetch this URL; confirm that it resolves].
+Every layer and every annotation lists both contexts, Web Annotation first:
 
 ```json
 {"@context": ["http://www.w3.org/ns/anno.jsonld", "https://scient.ing/ns/scienting/1.jsonld"]}
 ```
 
-The context maps the terms the formats add to annotations (`kind`, `status`, `audience`, `receipt`, `verdict`, `AnchorSelector`, `anchor` and others) to IRIs under `https://scient.ing/ns/scienting#`.
-`anchor` and `exercise` are JSON literals, so a JSON-LD processor keeps a `scienting-anchor/1` record intact instead of expanding it.
+The `scienting-` prefix is the formats' namespace, as in `scienting-layer/1` and `scienting-anchor/1`.
+The repository's name, manuspec, is a separate matter.
+
+## An example from the fixtures
+
+[`fixtures/records/layer/annotations.jsonl`](../fixtures/records/layer/annotations.jsonl) holds nine annotations on the example paper `hale2026harmonic`.
+The first is a `gloss`, an explanation for a novice, of the phrase "bond force constant".
+Shortened, it reads:
+
+```json
+{"@context": ["http://www.w3.org/ns/anno.jsonld", "https://scient.ing/ns/scienting/1.jsonld"],
+ "type": "Annotation", "motivation": "describing", "status": "confirmed",
+ "body": {"type": "TextualBody", "kind": "gloss", "audience": "novice",
+          "value": "A *harmonic* term treats a bond like a spring: ..."},
+ "target": {"type": "SpecificResource",
+            "source": "urn:scienting:doc:smithlab/hale2026harmonic",
+            "selector": [
+              {"type": "AnchorSelector",
+               "anchor": {"format": "scienting-anchor/1", "node": "sxgcc9h",
+                          "span": [111, 130], "quote": {"exact": "bond force constant", "...": "..."}, "...": "..."}},
+              {"type": "TextQuoteSelector", "exact": "bond force constant",
+               "prefix": "rm{eq}})^2$$ where $K_r$ is the ", "suffix": " and $r_\\mathrm{eq}$ the equilib"}]}}
+```
+
+The Web Annotation context defines `type`, `motivation`, `body`, `target`, `source`, `selector`, `exact`, `prefix` and `suffix`.
+This context defines `kind`, `status`, `audience`, `AnchorSelector` and `anchor`.
+
+## What it defines
+
+The file defines 23 terms.
+Twenty-two map to IRIs under `https://scient.ing/ns/scienting#`: `format`, `kind`, `status`, `receipt`, `layer`, `audience`, `visibility`, `purpose`, `project`, `docs`, `pin`, `role`, `symbol`, `verdict`, `reason`, `reference`, `for`, `generator`, `exercise`, `anchor`, `rights_use` and the class `AnchorSelector`.
+Three are renamed: `for` is `sct:questionFor`, `generator` is `sct:generatedBy`, and `rights_use` is `sct:rightsUse`.
+The twenty-third, `total`, maps to `totalItems` in the ActivityStreams namespace.
+Two terms carry a type rule.
+A processor reads `layer` as an IRI, and it always reads `docs` as a set, so a one-element list stays a list.
+
+The file declares `anchor` and `exercise` as JSON literals (`"@type": "@json"`, a JSON-LD 1.1 feature, which is why the file sets `"@version": 1.1`).
+A JSON-LD processor then keeps a `scienting-anchor/1` record intact instead of expanding it.
+An anchor holds hashes (fixed-length fingerprints of text) and a `span`, a pair of character offsets whose order carries meaning.
+Expansion would drop the anchor's unmapped field names and treat its arrays as unordered sets [CHECK: needs citation, JSON-LD 1.1 expansion rules].
+
+## The anchor selector and its fallback
+
+A selector says how to find a passage inside a source.
+The standard selectors work from the passage's text or its position.
+`TextQuoteSelector` holds the quoted text (`exact`, required) and optionally some text before and after it (`prefix`, `suffix`).
+`TextPositionSelector` holds start and end offsets, which the model itself calls "very brittle with regards to changes to the resource" ([Web Annotation Data Model](https://www.w3.org/TR/annotation-model/)).
+
+`AnchorSelector` is the custom selector of these formats.
+It carries a `scienting-anchor/1` record: the document key, the node ID, the node's `own_hash` and `node_hash` as they were when the anchor was made, an optional `span` in Unicode code points, a `quote`, and the document revision `rev` ([spec/06 §6.2](../spec/06-anchors.md#62-the-anchor)).
+A reader can use the hashes to resolve the anchor against a corrected document and report one of five outcomes: `current`, `changed-below`, `moved`, `reattached` or `stale` ([spec/06 §6.5](../spec/06-anchors.md#65-resolution)).
+A standard selector cannot do that.
+
+A tool that does not know `AnchorSelector` cannot use it.
+An annotation's `selector` list puts the `AnchorSelector` first and, where the anchor has a quote, a standard `TextQuoteSelector` after it, for tools that do not know ours ([spec/18 §18.3](../spec/18-layers.md#183-the-annotation)).
+The formats use no `TextPositionSelector` and no `FragmentSelector`.
+Such a tool still reads the annotation's body and its `TextQuoteSelector`; the context matters only to tools that process the data as linked data.
+That is the repository's statement; no Web Annotation client has been tested against these files [CHECK: confirm that no client test exists; the comparison source marks this unverified].
+
+The fallback is not always there.
+Three of the nine fixture annotations have only an `AnchorSelector` (the section-level question, the `generated` annotation on a figure and the exercise on a table), because the anchor points at a container and has no quote.
+
+## Using the context
+
+- Writer: Put both URLs (web addresses), in the order shown, in `@context` of `layer.json` and of every line of `annotations.jsonl`. [Chapter 18](../spec/18-layers.md) defines layers (§18.2), annotations (§18.3) and bodies (§18.4).
+- Reader: Follow [chapter 6](../spec/06-anchors.md) to resolve an anchor.
+  The file `vectors/resolve.jsonl` resolves seventeen anchors against `fixtures/packages/hale2026harmonic` and gives every outcome.
+- JSON-LD processor: Use a JSON-LD 1.1 processor; the context relies on `@json` and `@version` 1.1.
+- Checker: `schemas/annotation.schema.json` and `schemas/layer.schema.json` validate the files. `tools/check.py` also checks that each annotation's ID derives from its content and that the receipt at `fixtures/records/layer/receipt.json` covers each `confirmed` annotation.
+
+The traps:
+
+- No test vector pins the context, and nothing in `tools/` reads `scienting-1.jsonld`.
+  The schemas require only that `@context` be an array of at least two non-empty strings; they do not check the URLs.
+  A file with a wrong context can pass the checker and still expand wrongly.
+- `@context` is part of an annotation's content hash (the hash covers everything except `status`, `receipt` and `modified`).
+  Rewriting or reordering the array changes the hash that a receipt covers.
+- `format` is one term for two jobs: the layer's `format` (`scienting-layer/1`) and a text body's `format` (`text/markdown`).
+  The scienting context maps it to `sct:format` [CHECK: the Web Annotation context defines its own `format`; confirm that listing this context second overrides it].
+- A consumer that does not use a field must still preserve it when it rewrites a file.
+  A tool that rewrites layers must not drop the scienting terms ([spec/00 §0.4](../spec/00-introduction.md)).
+- The spec does not say what the `TextQuoteSelector` holds when the anchor's quote is hashed (over 200 code points) or keyed ([spec/06 §6.3](../spec/06-anchors.md#63-keyed-anchors)) [CHECK: spec/18 is silent; a plain fallback quote would put text in a public layer that the keyed anchor withholds].
+
+## Status and comparison
+
+The specification is version 0.1.0.
+`scienting-layer/1`, `scienting-anchor/1` and `scienting-exercise/1` are `candidate` in [`registry/formats.json`](../registry/formats.json).
+The specification defines `candidate` as "Complete, with vectors and fixtures, and ready to implement."
+The context file is normative ([spec/00 §0.5](../spec/00-introduction.md)).
+
+The W3C Web Annotation Data Model is a 2017 W3C Recommendation and the general standard for annotating web resources, with existing clients that form an ecosystem these formats do not have ([Web Annotation Data Model](https://www.w3.org/TR/annotation-model/)).
+Its standard selectors carry no content hash of the target text and define no outcomes such as `moved` or `stale`.
+Its remedy for a changing resource is to record a state of the whole resource.
+Hypothesis stores a quote selector with 32 characters of context and reattaches by fuzzy matching ([Hypothesis, fuzzy anchoring](https://web.hypothes.is/blog/fuzzy-anchoring/), 2013).
+These formats store a hash pin and define the outcomes exactly.
+The full comparison is in [docs/comparison.md](../docs/comparison.md).
 
-A Web Annotation tool that knows nothing of this context still reads the annotation's body and its `TextQuoteSelector`; the context matters only to tools that process the data as linked data.
 [Chapter 18](../spec/18-layers.md) defines layers and annotations.