feat: documents and session tokens

registry/README.md

@@ -0,0 +1,36 @@
+# Registry
+
+Lists that tools read at run time.
+
+| File | Holds |
+| --- | --- |
+| `formats.json` | Every format: its identifier, media type, schema, status and chapter. |
+| `rules.json` | Every validation rule ID, with what it means. |
+| `stamps/scienting-stamps-1.json` | The published rules that recognize publishers' download stamps, so page fingerprints ignore them. |
+| `stages/scienting-stages-default.json` | The rights each processing stage needs, as a default a team may replace. |
+
+## Rule IDs
+
+Validators report failures as `path:line: rule: message`, for example:
+
+```text
+nodes.jsonl:7: doc.hash.node-hash: node_hash does not recompute
+```
+
+A rule's meaning never changes, and a retired rule's ID is never reused, so tools and people can rely on the IDs.
+
+## Adding stamp rules
+
+When two downloads of one paper differ only in a stamp line that no published rule recognizes, record a rule in a file of your own, marked as learned:
+
+```json
+{"format": "scienting-stamps/1", "id": "smithlab-learned", "learned": true,
+ "rules": [{"id": "licensed-to", "pattern": "^This copy is licensed to .+", "where": "margin", "margin": 36}]}
+```
+
+Patterns use only syntax that ECMAScript and Python read alike, and match a line's normalized text, with ASCII letters compared without case.
+
+## Replacing the stage defaults
+
+The stage requirements are configuration, not code: licenses define text and data mining differently, so a team copies `scienting-stages-default.json`, adjusts it with its counsel, and points its project's settings at the copy.
+[Chapter 14](../spec/14-rights.md) explains how stages are checked.