Define draw, hold, pin, family, whole and fence in the package doc

README.md

@@ -1309,6 +1309,7 @@ the Development section below, and who ships a register the four above then draw
 ## Layout
 
 ```
+doc.go          the package doc, and the vocabulary the rest of it uses for a render and its fences
 fejkdata.go     Generator, New, options, the embedded data set, List
 node.go         the node model and JSON -> node compilation
 table.go        tables: the rows TSV, its options and links, row selection and draws

doc.go

@@ -0,0 +1,41 @@
+// Package fejkdata generates fake data from recursive JSON templates.
+//
+// Data lives in JSON, not in Go. A generator starts from the shipped data set and
+// layers any directories you add; folders and files become a dot-path namespace,
+// then generate values by path:
+//
+//	f, _ := fejkdata.New(fejkdata.WithSeed(42))
+//	f.Fake("sv_SE.address")          // "Järvedsvägen 43\n891 77 Järved"
+//	f.Fake("sv_SE.address.locality") // "Sundbyberg": a second call draws afresh
+//
+// Several sources merge in order, the last winning a name clash, so custom data
+// layers over the built-ins. The JSON template format is documented in the README.
+//
+// # Vocabulary
+//
+// The words the rest of the package uses, and the unit that owns each:
+//
+//   - draw — one pick from a choice, or one row taken from a table, and the value
+//     the pick produced: `pick` and `drawn` settle a choice, `table.draw` a row, and
+//     `draw` carries what a read produced.
+//   - expansion — one render of one format, by `expand`. A nested template is an
+//     expansion of its own, and so is each iteration of a `template.repeat`.
+//   - render — one `Fake` call or one record, started by `renderOnce` where nothing
+//     outer started it. It owns one `drawSet`, so it is what a reference draw spans.
+//   - hold — keeping one draw of a name, so every route to it reads that value.
+//     `template.held` lists what an expansion holds, `draws` keeps them and
+//     `readField` reads through it; a reference path is held for the whole render.
+//   - draw group — `template.drawGroup`, which gives the reference paths under it
+//     draws of their own inside the render. `drawSet` holds the unnamed group's and
+//     each named one's, and `drawScope` says which one a template renders in.
+//   - pin — fixing which row of a table the render uses. `draws.pin` pins it and the
+//     rows of its ancestors, and `draws.rowOf` draws one where none is pinned.
+//   - family — a table and every table reaching it through a chain of
+//     `table.parentT`, named by the root that chain ends at: `table.family`.
+//   - whole — a read that lands on a `row`, so the table's format renders every
+//     column of it: `tableRead.whole`.
+//   - fence — a load-time check refusing data that two routes to one draw would
+//     disagree in. Every one runs in `New`, which is why `Fake` cannot fail on
+//     loaded data: `heldCheck` over an expansion's held names, `drawCheck` over a
+//     render's reference paths, and `checkFamilies` over the rows they pin.
+package fejkdata

fejkdata.go

@@ -1,15 +1,3 @@
-// Package fejkdata generates fake data from recursive JSON templates.
-//
-// Data lives in JSON, not in Go. A generator starts from the shipped data set and
-// layers any directories you add; folders and files become a dot-path namespace,
-// then generate values by path:
-//
-//	f, _ := fejkdata.New(fejkdata.WithSeed(42))
-//	f.Fake("sv_SE.address")          // "Järvedsvägen 43\n891 77 Järved"
-//	f.Fake("sv_SE.address.locality") // "Sundbyberg": a second call draws afresh
-//
-// Several sources merge in order, the last winning a name clash, so custom data
-// layers over the built-ins. The JSON template format is documented in the README.
 package fejkdata
 
 import (

todo.md

@@ -21,9 +21,6 @@ name says whether a unit runs at `New` or at `Fake`.
 
 This round, in order:
 
-- Define the fence vocabulary where a reader of the code meets it: fence, hold, pin,
-  draw, draw group, expansion against render, family, whole. It exists only across five
-  README sections today, and every reader paid for it before the three files read at all.
 - Say on the `template` struct which pass fills which field, and that `compileFormat`
   runs a second time once `linkTemplateRefs` binds the references: nine of its fields
   are written by four other files, and the order lives only in `loadData`'s body.