feat: documents and session tokens

spec/00-introduction.md

@@ -2,13 +2,11 @@
 
 ## 0.1 Scope
 
-These specifications define the data the Scientific Computing Studio's parts write and read: documents and their packages, anchors, receipts, rights records, layers, exercises, datasets, digitizations, views, projects and bundles.
+These specifications define the data that tools for reading, correcting, annotating and checking scientific papers exchange: documents and their packages, anchors, receipts, rights records, layers, exercises, datasets, digitizations, views, projects and bundles.
 They define data, not programs.
-A conforming file can be read, checked and loaded without any studio code, and every rule here is stated so that a second implementation, in any language, computes the same bytes.
+A conforming file can be read, checked and loaded without any particular program, and every rule is stated so that a second implementation, in any language, computes the same bytes.
 
-The design document, *The Scientific Computing Studio: design of Lode, paperpack and Varve*, explains why each format exists.
-This text says exactly what each format is.
-Where the two differ, this text governs, and [DECISIONS.md](../DECISIONS.md) records why it differs.
+The [guides](../docs/README.md) explain what each format is for, and the [rationale](../docs/rationale.md) why its rules are what they are.
 
 ## 0.2 Conformance language
 
@@ -39,16 +37,16 @@ The specification as a whole is versioned with semantic versioning; this is vers
 
 ## 0.4 Status
 
-Each format has one of three statuses.
+Each format has one of three statuses, listed in [registry/formats.json](../registry/formats.json).
 
 | Status | Meaning |
 | --- | --- |
-| `candidate` | Complete, with vectors and fixtures, and ready to implement. Changes before 1.0 need a recorded decision. |
-| `provisional` | Complete, but its milestone has not come, and it may change with less ceremony. |
+| `candidate` | Complete, with vectors and fixtures, and ready to implement. |
+| `provisional` | Complete, but expected to change as implementations gain experience with it. |
 | `reserved` | Named and shaped, but not yet specified in full. |
 
-The design builds in levels, and level 1 implements a subset.
-Fields that level 1 does not use, such as rights beyond the license, receipts and spot-checks, are defined now so that formats never change when a team moves up a level.
+Some fields matter only to some users: a personal library has no use for spot-checks, and a team that reads only open-access papers rarely needs a policy.
+Those fields are defined all the same, so that files move between a personal library and a team's store without conversion.
 A consumer that does not use a field MUST still preserve it when it rewrites a file.
 
 ## 0.5 How the repository is arranged
@@ -62,7 +60,8 @@ A consumer that does not use a field MUST still preserve it when it rewrites a f
 | `registry/` | Formats, rule IDs, stamp rules and the default stage requirements. | Yes |
 | `vectors/` | Test vectors, one case per line. | Yes |
 | `fixtures/` | Valid packages and records, invalid packages, and the keys that signed them. | Yes |
-| `tools/` | The oracle that computed the vectors, the builder and the checker. | No |
+| `tools/` | The programs that compute and check the vectors and fixtures, and load packages into SQLite. | No |
+| `docs/` | Guides for people getting to know the formats. | No |
 
-The oracle exists so that no vector is typed by hand.
-It is not a library: implementations conform to the chapters and the vectors, not to the oracle, and `scienting-core` is the reference implementation.
+The programs in `tools/` compute every expected value, so that none is typed by hand.
+They are not a library: implementations conform to the chapters and the vectors, and `scienting-core` is the reference implementation of the shared rules.