Move the prose trees under docs/

.github/workflows/build-and-test.yml

@@ -31,19 +31,19 @@ jobs:
         with:
           fetch-depth: 0
       # A Markdown file counts as prose unless a suite reads it: the kernel
-      # and bun suites read spec/ and the guide under packages/, and a dune
+      # and bun suites read docs/reference/ and the guide under packages/, and a dune
       # file can name a decision as a test dependency.
       - name: Decide whether the pull request changes more than prose
         id: files
         env:
           BASE: ${{ github.event.pull_request.base.sha }}
           HEAD: ${{ github.event.pull_request.head.sha }}
         run: |
-          read_by_suites=$(grep -rhoE 'decisions/[^ )]+\.md' --include=dune packages | sort -u)
+          read_by_suites=$(grep -rhoE 'docs/decision/[^ )]+\.md' --include=dune packages | sort -u)
           code=false
           while read -r f; do
             case "$f" in
-              spec/* | packages/*) code=true ;;
+              docs/reference/* | packages/*) code=true ;;
               *.md) if grep -qxF "$f" <<<"$read_by_suites"; then code=true; fi ;;
               *) code=true ;;
             esac

.github/workflows/deploy.yml

@@ -15,7 +15,7 @@ on:
       - 'packages/core/tests/**'
       # The reference documents are symlinked into the site, and their figures
       # are generated from them by scripts/build-api-docs.sh.
-      - 'spec/**'
+      - 'docs/reference/**'
       # check-all compares the README drawings with the programs they show.
       - 'examples/**'
       - 'scripts/**'

.vale/styles/config/vocabularies/Beloch/accept.txt

@@ -518,3 +518,4 @@ XOR'd
 Zakharevich
 zarith
 Zenodo
+Spalier

CLAUDE.md

@@ -2,9 +2,9 @@
 
 Beloch writes origami folding sequences as programs over the Huzita-Justin
 axioms. It evaluates `.bel` source into one FOLD file with the folded state after
-every step; crease patterns and YR-style folding diagrams are renderings of it. Architecture decisions live in `decisions/` (ADRs); read those
-before proposing anything structural. Design journal in `notes/`, dead ends in
-`notes/antipatterns.md`. The contracts live in `spec/`: `MODEL.md` what a
+every step; crease patterns and YR-style folding diagrams are renderings of it. Architecture decisions live in `docs/decision/` (ADRs); read those
+before proposing anything structural. Design journal in `docs/notes/`, dead ends in
+`docs/notes/antipatterns.md`. The contracts live in `docs/reference/`: `MODEL.md` what a
 program means, `BELOCH.md` the language, `FOLD.md` the output. Beside them,
 binding no other implementation: `KERNEL.md` what `packages/core` realizes,
 `CLI.md` the `beloch` command. `SPECIFICATION.md` is being dissolved into
@@ -17,8 +17,8 @@ Per-slice design documents are not kept in the working tree. They were
 point-in-time records of how one slice was built, they went stale as the code
 moved on, and code comments pointing into them taught readers things that had
 stopped being true. What a slice decided belongs in an ADR, what it contracts
-in `spec/`, and what it is worth remembering about a dead end in
-`notes/antipatterns.md`. The documents themselves stay in the Git history;
+in `docs/reference/`, and what it is worth remembering about a dead end in
+`docs/notes/antipatterns.md`. The documents themselves stay in the Git history;
 `git log --diff-filter=D --stat -- docs/superpowers/specs` finds them.
 
 A skill that writes a spec or a plan to `docs/superpowers/` writes it to the
@@ -77,7 +77,7 @@ for `dune build`.
 CI runs `check` on every pull request, in the job `build-and-test` of
 `.github/workflows/build-and-test.yml`, and skips it when the pull request
 changes only Markdown that no suite reads. A push to `main` that touches the
-site, the kernel, `spec/`, `examples/`, `scripts/` or the flake runs
+site, the kernel, `docs/reference/`, `examples/`, `scripts/` or the flake runs
 `check-all` in the deploy job, which deploys the site when it passes; any
 other push to `main` runs only the commit subject check.
 
@@ -143,7 +143,7 @@ list of what needs Toph's decision or action, or say that nothing does.
 
 ## Math notation
 
-In `notes/`, `docs/` and memos, formulas are LaTeX math (`$...$` inline,
+In `docs/` and memos, formulas are LaTeX math (`$...$` inline,
 `$$...$$` display); GitHub, Forgejo and the VS Code preview render KaTeX.
 Symbol names (`AL8`), code identifiers and paths go in backticks, never bare.
 Chat gets words instead of LaTeX, since the terminal does not render it.

README.md

@@ -71,7 +71,7 @@ Five verbs write to the paper. `mark` scores a crease and moves nothing,
 `flip` turns the paper over, and `flatten` folds a vertex flat along several
 rays at once; given an odd number of them, it derives the one ray that is
 missing. The evaluator works out where every layer goes and which creases end
-up mountain or valley. The full grammar is in [`spec/BELOCH-GRAMMAR.md`](spec/BELOCH-GRAMMAR.md)
+up mountain or valley. The full grammar is in [`docs/reference/BELOCH-GRAMMAR.md`](docs/reference/BELOCH-GRAMMAR.md)
 and on the [grammar page](https://belochlang.org/language/grammar/).
 
 ## Related work
@@ -118,7 +118,7 @@ is one.
 Both rest on the language: a program is a finite sequence of constructions and
 folds, with no loops, no recursion (a `def` sees only earlier `def`s) and no
 host language
-([decision 0009](decisions/0009-relationship-to-rabbit-ear.md)). Every program
+([decision 0009](docs/decision/0009-relationship-to-rabbit-ear.md)). Every program
 terminates, its statements are its folding sequence, and every crease in the
 FOLD output names the statement and the construction that made it.
 
@@ -130,12 +130,12 @@ FOLD output names the statement and the construction that made it.
   state, and the test suite checks assertions on them. Programs for the
   jumping frog, the flapping bird and the traditional frog are drafts; each
   stops at a step the kernel cannot fold yet.
-- **Formalized:** [`spec/MODEL.md`](spec/MODEL.md) defines folded states and
+- **Formalized:** [`docs/reference/MODEL.md`](docs/reference/MODEL.md) defines folded states and
   the operations on them. Its first sections are reviewed; the section on
   operations is a draft, and two of its lemmas, among them that a fold
   introduces no crossing, have pending proofs.
 - **Not yet:** Yoshizawa-Randlett folding diagrams, 3D states
-  ([decision 0015](decisions/0015-flat-folded-states-only.md)), and
+  ([decision 0015](docs/decision/0015-flat-folded-states-only.md)), and
   measurements on programs longer than a few dozen statements.
 
 ## Running it

decisions/0005-name-beloch.md → docs/decision/0005-name-beloch.md

@@ -22,7 +22,7 @@ Name the language **Beloch**, after **Margherita Piazzolla Beloch**.
 - Her 1936 work showed origami constructions solve general cubic equations,
   making paper-folding more powerful than straightedge-and-compass.
 - The **Beloch fold is axiom 7** in the Huzita-Justin numbering this project
-  uses (see "Numbering" in `spec/SPECIFICATION.md`). Justin ordered the seven
+  uses (see "Numbering" in `docs/reference/SPECIFICATION.md`). Justin ordered the seven
   axioms by algebraic power, so the Beloch fold is the last and strongest one:
   the single hardest thing in the language to handle, with up to three
   solutions, no closed form, and the disambiguation problem the design keeps

decisions/0013-flint-qqbar-backend.md → docs/decision/0013-flint-qqbar-backend.md

@@ -14,7 +14,7 @@ the `Mpoly` elimination pipeline of 0012 remain)
 
 ADR 0012's `Alg` (squarefree polynomial + isolating interval, resultant
 arithmetic) was correct but had two walls, measured in
-`notes/2026-07-03-flint-kernel-spike.md`: cross-field chains grow degree
+`docs/notes/2026-07-03-flint-kernel-spike.md`: cross-field chains grow degree
 multiplicatively without normalization (comparing (∛2+√2)² against ∛2+√2:
 >120 s), and composite extensions of degree ≥ 4 were not representable
 without a polynomial factorizer. Building the D5-style fix ourselves
@@ -64,4 +64,4 @@ wired through the flake.
   libraries (nix development shell / flake). `to_float` gains a sibling
   (`Qqbar.to_float`), still output-only.
 - #33's stacked-cubic ceiling question is re-answered by benchmark
-  (`notes/2026-07-03-flint-kernel-spike.md` + the #33 verdict note).
+  (`docs/notes/2026-07-03-flint-kernel-spike.md` + the #33 verdict note).

decisions/0014-crease-is-a-bundle-of-segments.md → docs/decision/0014-crease-is-a-bundle-of-segments.md

@@ -51,8 +51,8 @@ not the line, is the durable referent of a crease name.
 The surface mechanisms (`at`, `pinch`) and their exact syntax are a
 specification/slice concern, not this decision; the durable decision is the
 bundle model itself. Full design:
-`notes/2026-07-03-crease-segment-at-operator.md` and
-`notes/2026-07-03-crease-layer-selection.md`.
+`docs/notes/2026-07-03-crease-segment-at-operator.md` and
+`docs/notes/2026-07-03-crease-layer-selection.md`.
 
 ## Alternatives considered
 - **Keep "crease = line", add a separate segment type.** Rejected: it denies what
@@ -82,5 +82,5 @@ bundle model itself. Full design:
 - Implementation is mostly additive: `fold_state` edges already carry `crease_id`
   + endpoints, so `at` is a query over the existing subdivision; `pinch` is a
   narrowed `subdivide` plus a display flag on the edge.
-- The spec (`spec/SPECIFICATION.md`) is extended only when the implementing slice
+- The spec (`docs/reference/SPECIFICATION.md`) is extended only when the implementing slice
   lands; until then this feature sits in Appendix B.

decisions/0015-flat-folded-states-only.md → docs/decision/0015-flat-folded-states-only.md

@@ -31,7 +31,7 @@ is stacking order (`faceOrders`). This is the **all-layers simple-fold** model,
 most restricted class in Demaine and O'Rourke's simple-fold taxonomy (one-layer /
 all-layers / some-layers) [demaine2007, §14.1.1].
 
-Nothing in `decisions/` recorded this scope, and the design doc's "already carried"
+Nothing in `docs/decision/` recorded this scope, and the design doc's "already carried"
 phrasing invited building on a 3D guarantee that does not exist.
 
 ## Decision

decisions/0016-typed-operands-bundle-values-singleton-slots.md → docs/decision/0016-typed-operands-bundle-values-singleton-slots.md

@@ -79,5 +79,5 @@ One operand model for the whole language:
 
 ## References
 - ADR 0011 (action model), ADR 0014 (crease = bundle of segments)
-- `notes/2026-07-03-crease-layer-selection.md` (pinch/at convergence)
+- `docs/notes/2026-07-03-crease-layer-selection.md` (pinch/at convergence)
 - [demaine2007, §14] for the simple-fold models motivating fold scope

decisions/0017-flap-is-coplanar-not-precrease-partition.md → docs/decision/0017-flap-is-coplanar-not-precrease-partition.md

@@ -260,7 +260,7 @@ already face-granular and unchanged.
 
 - ADR 0014 (a crease is a bundle of segments: why faces stay fine-grained)
 - ADR 0016 (typed operands: the flap operand type this ADR redefines)
-- `spec/SPECIFICATION.md` §4.6 (`@` / `@fold` / `moving` / `up to`), §4.8 (`at`)
+- `docs/reference/SPECIFICATION.md` §4.6 (`@` / `@fold` / `moving` / `up to`), §4.8 (`at`)
 - `packages/core/tests/cases/bases/rabbit-ear.bel` (the repro for both findings)
 - `lib/fold_state.ml` (`flap_of_points` :352, `select_scope` :385,
   `type assign`, `subdivide`); `lib/eval.ml` (`resolve_flap_face`,

decisions/0025-construction-candidate-selection-material-stand-alone.md → docs/decision/0025-construction-candidate-selection-material-stand-alone.md

@@ -9,7 +9,7 @@ status: accepted
 
 ## Context
 
-`spec/MODEL.md` defines four things inside the body of one definition. Read
+`docs/reference/MODEL.md` defines four things inside the body of one definition. Read
 `def-motion`: an *alignment* is an incidence on the table between two objects,
 one of them reflected across the line sought; a *construction* is a finite set
 of alignments that determines the line, with finitely many solutions and no
@@ -69,7 +69,7 @@ refinements of one state yields two states with a common refinement. That
 statement is recorded as an open question beside the definition.
 
 `motion` keeps its meaning and is not reused. The word is already load-bearing
-twice in `spec/MODEL.md`, both times for movement the model does not model:
+twice in `docs/reference/MODEL.md`, both times for movement the model does not model:
 "the model checks the end state and never the motion", and "immaterial for the
 state up to a motion of the table". A third meaning would have made the first
 of those read as if the model skipped checking its own writes.
@@ -106,7 +106,7 @@ and `line` as partial from a state and a bundle to a table line.
 ## Consequences
 
 - The model, the language reference and the core rename together.
-  `spec/SPECIFICATION.md` carries `<motion>` as a syntax category in about ten
+  `docs/reference/SPECIFICATION.md` carries `<motion>` as a syntax category in about ten
   places, so the rename is a documentation change before it is a code change.
 - A glossary entry can now disagree with the definition that owns it: a
   signature naming a sort the model does not define, or a kind that contradicts

decisions/0027-the-meet-is-an-intersection-of-point-sets.md → docs/decision/0027-the-meet-is-an-intersection-of-point-sets.md

@@ -12,7 +12,7 @@ status: accepted
 The meet, `--x * --y` and its n-ary form `.[--x --y …]`, names the point
 where creases cross. Until v0.19 it intersected the operands' table lines and
 resolved the table point to the topmost layer covering it. That rule is
-recorded as a dead end in `notes/antipatterns.md` (Q2-B) for two reasons.
+recorded as a dead end in `docs/notes/antipatterns.md` (Q2-B) for two reasons.
 Paper is opaque, so the topmost layer may carry neither crease, and the rule
 named points that no layer of the paper shows. And a point construction came
 to depend on the folded state, while a crease is a scar whose crossings in the

decisions/0028-an-error-carries-its-hint-apart-from-its-message.md → docs/decision/0028-an-error-carries-its-hint-apart-from-its-message.md

@@ -44,7 +44,7 @@ Every reader carries both halves to its reader:
 
 No message carries a suggestion of its own. The existing suggestions move into
 hints in the same change that introduces them, and the error table in
-`spec/SPECIFICATION.md` quotes message and hint in separate columns.
+`docs/reference/SPECIFICATION.md` quotes message and hint in separate columns.
 
 ## Alternatives considered
 

decisions/0029-annotations-pass-through-and-each-output-is-a-library.md → docs/decision/0029-annotations-pass-through-and-each-output-is-a-library.md

@@ -22,7 +22,7 @@ knows these things, and today the program has no place to say them.
 
 ADR 0002 planned a small, versioned JSON schema for step-by-step diagrams,
 beside the FOLD. Since then the FOLD has grown what that schema would have
-carried. It holds one frame per state (`spec/FOLD.md`), and ADR 0026 put every
+carried. It holds one frame per state (`docs/reference/FOLD.md`), and ADR 0026 put every
 statement into `beloch:statements` with its kind, its source span and the
 frame it stands on. A consumer can walk the program and the states without
 parsing the source.
@@ -33,7 +33,7 @@ no picture. A shared instruction schema would either take the smallest common
 part of these or grow a branch per medium, and in both cases the real layout
 work would still happen in each consumer.
 
-The fused `step` construct (`notes/antipatterns.md`) shows the risk on the
+The fused `step` construct (`docs/notes/antipatterns.md`) shows the risk on the
 language side: display grouping and scoping were one construct and came apart
 under pressure. Whatever marks a step for a diagram must group and do nothing
 else.
@@ -42,7 +42,7 @@ else.
 
 **Annotations are written in the `.bel` source.** An annotation attaches to a
 statement or to a contiguous range of statements. Its syntax belongs to
-`spec/BELOCH.md`; `#[ … ]` is the flap selector and is not available.
+`docs/reference/BELOCH.md`; `#[ … ]` is the flap selector and is not available.
 
 **An annotation never changes the geometry.** The front end separates
 annotations from the program, and the geometric evaluation (ADR 0007, phase 2)
@@ -77,7 +77,7 @@ annotations together are everything an output reads. The annotations live in
 one top-level field, one entry per annotation, each naming its target as a
 range of indices into `beloch:statements`. A range fits the step group, which
 spans statements and frames, and a single statement is a range of length one.
-The field-level contract goes into `spec/FOLD.md`.
+The field-level contract goes into `docs/reference/FOLD.md`.
 
 **Each output kind is a TypeScript library at the edge (ADR 0001).** A library
 offers two sets of primitives:
@@ -126,12 +126,12 @@ favor of the libraries; its editor boundary, LSP, stands in ADR 0007 as
 
 ## Consequences
 
-- The front end, the emitter, `spec/BELOCH.md` (syntax) and `spec/FOLD.md`
+- The front end, the emitter, `docs/reference/BELOCH.md` (syntax) and `docs/reference/FOLD.md`
   (the annotation field) change together; the geometric evaluation does not
   change.
 - The invariance test becomes part of `check`. A kernel change that lets an
   annotation reach the geometry fails it.
-- `spec/BELOCH.md` already calls the intent item `(mountain)`, `(valley)` an
+- `docs/reference/BELOCH.md` already calls the intent item `(mountain)`, `(valley)` an
   annotation. Intent reaches the FOLD as `edges_assignment` and constrains a
   `flatten`, so it is part of the geometry and stays an item of its statement.
   The word in that table changes, so that "annotation" means one thing.
@@ -154,7 +154,7 @@ favor of the libraries; its editor boundary, LSP, stands in ADR 0007 as
   the annotation would resolve names against the program without writing.
   It is the next entry for the vocabulary once the first three are in use.
 - **Values.** The first vocabulary needs text, numbers and label references.
-  Beloch has no text literal yet, and `spec/BELOCH.md` adds one with the
+  Beloch has no text literal yet, and `docs/reference/BELOCH.md` adds one with the
   syntax.
 - **How the CLI finds an author's own function** in place of a library's
   default. This belongs to the CLI once the first library exists.

decisions/0030-the-fold-logs-the-program-flat.md → docs/decision/0030-the-fold-logs-the-program-flat.md

@@ -115,7 +115,7 @@ body to learn what happened.
 ## Consequences
 
 - One source span can now occur in several entries, one per `apply` that ran
-  its statement. Consumers join on the entry index, which `spec/FOLD.md`
+  its statement. Consumers join on the entry index, which `docs/reference/FOLD.md`
   already asks of `beloch:edges`.
 - A renderer finds a repetition by grouping the `apply` entries by the `def`
   they name. The diagram library draws the second one as a repeat of the
@@ -128,5 +128,5 @@ body to learn what happened.
 - A FOLD written before this change carries no `apply` entries and no body
   bindings. A reader treats an entry without a parent as top-level, and an
   entry without a kind as a write, as ADR 0026 already required.
-- The evaluator, `spec/FOLD.md`, the scene parser and the runtime core change
+- The evaluator, `docs/reference/FOLD.md`, the scene parser and the runtime core change
   together. The stepper walks the writes as before and sees no difference.

decisions/0031-toward-names-the-side-that-stays.md → docs/decision/0031-toward-names-the-side-that-stays.md

@@ -168,8 +168,8 @@ leaves the construction.
 
 ## Consequences
 
-- `def-selection` in `spec/MODEL.md` states the selection and the condition
-  every fold puts on its candidates. `spec/BELOCH.md` moves `toward` out of
+- `def-selection` in `docs/reference/MODEL.md` states the selection and the condition
+  every fold puts on its candidates. `docs/reference/BELOCH.md` moves `toward` out of
   the construction, adds `heading` and `(x toward …)`, parenthesizes the parts
   of `align`, and gives bindings items. The prose form of axiom 5 loses its
   `toward`.

decisions/0032-the-specification-binds-every-implementation.md → docs/decision/0032-the-specification-binds-every-implementation.md

@@ -55,7 +55,7 @@ catalog on pages of their own. It is never divided by layer into
 vocabulary, syntax and semantics: each construct keeps its syntax,
 resolution, errors and example together, and its meaning stays in the model.
 
-The rule of `spec/README.md` holds: the documents are divided by role and
+The rule of `docs/reference/README.md` holds: the documents are divided by role and
 reader, never by increment. A slice that changes the language edits the
 document whose role it touches.
 
@@ -79,7 +79,7 @@ shrinks, so that at no point the grammar is nowhere.
    Version history moves to the changelog, the appendix of deferred features
    to issues, one per entry.
 3. `SPECIFICATION.md` is deleted; the links to it in ADRs, notes, the README
-   and `spec/` are redirected to the section that now holds the content.
+   and `docs/reference/` are redirected to the section that now holds the content.
 
 Until step 3 completes, a section still in `SPECIFICATION.md` is
 authoritative for the surface syntax, never for the meaning.