The Meta Level

The background chapters

2026-08-13T00:00:00.000Z

The report is a summary. These are the working chapters behind it — one set per layer of the model, in the order the layers bind. They are written for someone checking the arithmetic rather than reading for pleasure, which is why they sit back here rather than in the listings.

Every figure in them regenerates from raw Environment Agency, BGS and Defra data.

The pipeline

How the layers fit together, and what regenerates what.

The pipeline — How the layers fit together. One directory per layer; this ties them.
V1 manifest — what reproduces, and what does not — The state of the project at the end of the scheme-layer batch, 2026-08-11. Written to the same standard as archive/v0/MANIFEST.md: what is here, what reproduces, and what does not.

The water layer

Rainfall in, river flow out, and the water table underneath.

The water layer — How water moves through this landscape before anybody builds anything.
The runoff model - and the split — Generated by build_runoff_model.py. Two linear reservoirs in parallel off one split fraction, calibrated against FLOW (which closes a water balance) on the first 70% of each…
River routing - flow at a point that is not a gauge — Generated by build_river_routing.py. The chapter the scheme layer is blocked on: an intake is never at a gauge.
The rhynes - the low-level watercourses — Generated by build_rhynes.py. The drainage network of the Levels, which every previous dataset in this project left out.
The water table — Generated by build_water_table.py. Fitted so that saturated thickness stops being the full thickness of the rock.
Is the water table dynamic? — Yes - and the static fit in water_table.md does not capture any of it. That fit reduced ~4,100 days of daily record per station to one mean. This goes back to the series.
A rainfall-driven water table — Generated by build_wt_coupled.py. Step 2 of next_steps.md, built on the same store the runoff model uses, with the signed-exchange departure agreed before building.
A rainfall-driven water table — high evapotranspiration — Generated by build_wt_coupled.py. Step 2 of next_steps.md, built on the same store the runoff model uses, with the signed-exchange departure agreed before building.
A rainfall-driven water table — low evapotranspiration — Generated by build_wt_coupled.py. Step 2 of next_steps.md, built on the same store the runoff model uses, with the signed-exchange departure agreed before building.

The aquifer layer

Which rock could hold water, how much, and how well it is known.

The aquifer layer — What the rock is, where it is, and how much water it can hold.
Rock layers, drawn from the boreholes — Generated by build_rock_layers.py. The polygons take no part in the drawing - they are scored against it below.
Layer model — two passes and a ledger — Generated by build_layer_model.py. Pass 1 is the defensible model. Pass 2 is everything admitted on an assumption, and every assumption is in the ledger.
Borehole data — what we hold and what we have read — Supporting file for the aquifer write-up. Living document: updated as logs are read. Generated maps come from map_boreholes.py; the readings live in borehole_sections.py.
Located aquifer inventory — Generated by inventory_aquifers.py. Every known aquifer body within 40 km of the site-screen box, with its location.
Depths, thicknesses and volumes — Generated by build_aquifer_volumes.py. Every body in aquifer_inventory.md, sized - with the confidence of every cell carried through and the weakest one governing.
Click targets — Paste back whatever each popup gives — formation name, age, and the LEX code if the More Information page shows one. Even the name alone is enough.
The portfolio re-screen — Generated by screen_portfolio.py. Every unit we hold information on, re-tested against a LOWER bar - not ‘is this the MAR store’ but 'does this have any role in an integrated…
Aquifer mapping - where we stand — Generated by aquifer_mapping_status.py. Three sources, kept separate on purpose: where they disagree, the borehole wins.
Data we cannot fetch ourselves — manual retrieval note — For papers/aquifers. Ordered by likely impact on the model, highest first. Everything here was attempted programmatically and failed, or is not served by any open endpoint.
Next steps — the modelling roadmap — Distinct from data_gaps.md, which lists data we cannot fetch. This lists work to do, in the order it has to be done, and says what each step unblocks. Written 2026-08-11.
Appendix - estimates, and what they rest on — Generated by estimate_aquifer_unknowns.py. Every number in the aquifer model that is not a measurement is listed here. Nothing below is hidden in a script.

The demand layer

What the water would be for, and why demand is not the constraint.

The demand layer — Who needs how much water, when, and what happens if they do not get it.
What demand data actually exists — What was looked for, what was found, what was fetched, and what still needs asking for. First chapter of the demand layer.
Licensed abstraction, scaled — Generated by build_demand_abstraction.py. Replaces the blanket 3 Mm3/yr with a figure that has a source - and a stated weakness.
A demand series with a rhythm — Generated by build_demand_series.py. Shape from physics, level from the licence.

The scheme layer

What you would build, and in what order you are allowed to decide it.

The scheme layer — What you would actually build, and in what order you are allowed to decide it.
Availability - what the rivers will give up — Generated by build_scheme_availability.py. First chapter of the scheme layer: the resource, before anything is built to catch it.
The design rule, tested — Generated by build_scheme_design.py.
Fill fast, empty slow - does the concept hold? — Generated by build_operating_concept.py.
Sizing - what each scheme delivers when it is needed most — Generated by build_scheme_sizing.py. A capability curve, not a recommendation.
Scheme options - realistic reservoirs, no reservoir, and several smaller ones — Generated by build_scheme_options.py. The three follow-ups to sizing.
Reconciling the portfolio contradiction — Generated by build_scheme_reconcile.py.
Pump sizing - how many units, and where — Generated by build_pump_sizing.py. No model run: arithmetic on the divertible series.
Aquifer operation - the capacitor — Generated by build_scheme_aquifer.py. Second chapter of the scheme layer: what the ground can take, hold and give back.
Pairing aquifers - leakage as the delivery mechanism — Generated by build_scheme_pairing.py.
The gravity screen - searching for what the old screen excluded — Generated by build_gravity_screen.py.
Can any basin be filled by gravity? — Generated by build_gravity_sites.py.
Drought tests - today, and six years of it — Generated by build_drought_tests.py.
Synthesis - three schemes, and the shape of the space — Generated by build_scheme_synthesis.py. Closes the loop opened by availability.

← Back to the report

Banking winter water for a dry summer

2026-08-13T00:00:00.000Z

July 2026 has been the driest July in the seventeen-year record: 4.5 mm of rain against a July average of 57 mm. That is the problem in one number.

148 — million m³ a year could lawfully be taken at high flows
86% — of it arrives between November and March
2% — arrives in June, July and August, when it is wanted
9 — bursts a year, each lasting about two days
The water exists — many times more than any scheme here would use.
It arrives in short bursts. This, not the annual total, is what makes the engineering hard.
A reservoir alone cannot bridge a drought. It empties every summer and refills every winter, so it carries nothing from one year to the next. Underground storage can — if the water stays put.
The most promising options are not the obvious ones: a basin that fills itself by gravity, and flood-storage moors that already exist.
No scheme is being recommended here. Nothing in this study is costed.

What changed since version 1

Version 1 was circulated on 12 August. Five things have changed, and two of them are corrections rather than additions.

A correction. Version 1 quoted a 389-day half-life beside a 15.7 million m³ capacity. Both were right for their own well field — one for a 1 km radius, one for 2 km — and wrong together. Everything is now quoted for the same 2 km field. No model run changed.
A correction. Option E was described as pairing two different rocks. It was not: both its stores had the same rock and differed only in size. It has been rebuilt on two formations that really are different.
Every rock body now carries a leakage figure. Version 1 left nine of fourteen blank. They are estimated from rock type and flagged as such — a blank read as “nothing is known”, which was not true.
An eighth option, H: the same scheme as C on the best untested rock, to price what better ground is worth.
New maps and charts: where each option would sit, what reaches the rivers, and how each scheme behaves through the year.

The ranking of the options is unchanged.

The current situation

The Somerset Levels flood in winter and run short in summer. Both happen for the same reason: the ground is flat, the rivers are slow, and the water arrives when nobody wants it.

Where the water is, and where the rock is. The dense blue mesh is the Levels’ drainage network — some 1,700 km of rhynes below 10 m above sea level. Red circles are the rock bodies that could store water; note that they sit on the western edge, away from the largest rivers.

86% of the water that could lawfully be taken arrives between November and March. Only 2% arrives in June, July and August. Any scheme here is therefore a battery, not a tap: its job is to move water across six months, not to find more of it.

In a drought year there is very little to catch. The surplus is a winter thing — nearly all of it arrives between November and March — so a drought year here means a winter whose floods never came. In the worst year of the record only 21% of the average was available to take.

Water given out in a dry summer was caught the previous winter, or the one before that. It cannot be topped up during the drought, because the drought is the failure of the winter that would have filled it.

What limits a reservoir here

This is flat, low, soft ground with high land value and deep peat in places.

Assumption

Much above 5 million m³ is taken to be an unrealistic cell on this ground. That is a judgement, not a calculation. It matters, because to stop losing water over the spillway entirely you would need around 10 million m³ — so a reservoir here will always take a share of the winter surplus.

Eight places the ground is the right shape. Each is a bunded cell of roughly 5 million m³ sitting beside a river, with the pipe that would fill it shown dotted. This is a terrain screen and nothing more: it says the shape of the land works, not that the land is available, the peat is shallow enough, or anyone would sell it. What it does show is that the constraint is not finding one site — it is that no single site on this ground gets much past 5 million m³.

What limits an aquifer

Water can also be put underground into porous rock and pumped back later. This is done elsewhere; the largest UK example supplies London. Underground storage does not evaporate and can hold water between years — but:

It leaks. Water spreads away from where you put it. A 2 km well field in the local sandstone loses half of what is in it in about four years; a smaller field loses it faster, and the same rock can be either.
It is fullest when you want to fill it. The water table peaks in February, exactly when the surplus arrives.
Nothing in seventeen years of local records contains an injection.

Red holds water between years; brown hands it back within weeks. Hatching marks the ten bodies whose leakage is estimated from rock type rather than measured — which is most of the map, and is the honest state of the evidence. The three brown bodies are the fractured limestones: useless as a bank, and exactly what option E needs as a river feed.

The table below is every body, with the same 2 km well field assumed on each so the rows can be compared.

Body	Rock	Size	Distance to a river	Half the water has spread away in	What that well field holds	Where the figures come from
A5	Upper Greensand Formation	203 km²	0.1 km	6 years	18.8 Mm³	guessed
A1	Helsby Sandstone Formation	177 km²	0.0 km	4 years	15.7 Mm³	measured
A6	Upper Greensand Formation	72 km²	0.7 km	6 years	18.8 Mm³	guessed
A7	Upper Greensand Formation	45 km²	0.0 km	6 years	18.8 Mm³	guessed
A8	Upper Greensand Formation	39 km²	0.2 km	6 years	18.8 Mm³	guessed
A9	Upper Greensand Formation	32 km²	0.2 km	6 years	18.8 Mm³	guessed
A2	Helsby Sandstone Formation	25 km²	4.4 km	4 years	15.7 Mm³	measured
A13	Exeter Group	22 km²	2.2 km	5 years	22.6 Mm³	inferred
A3	Helsby Sandstone Formation	16 km²	0.5 km	4 years	15.7 Mm³	measured
A14	Chalk (Salisbury Plain body)	7 km²	1.8 km	2 days	0.2 Mm³	guessed
A4	Helsby Sandstone Formation	2 km²	2.6 km	4 years	15.7 Mm³	measured
A10	Great Oolite Group	408 km²	0.0 km	30 days	2.5 Mm³	guessed
A12	Carboniferous Limestone Supergroup	21 km²	0.0 km	15 days	1.3 Mm³	guessed
A11	Great Oolite Group	1 km²	3.4 km	30 days	2.5 Mm³	guessed

Size of body barely matters; kind of rock matters a lot. Underground storage is not a tank filled to the edges of the rock. It is a mound of water around a ring of wells, so its volume is set by the ring and by what the rock will give up — not by how much rock there is. The 408 km² Oolite body and the 1 km² one offer the same 2.5 Mm³ to the same well field. But the Greensand offers 18.8 and the limestones 1–2, because they differ in how much water drains out of them.

Only the sandstone rests on measured figures. Every other row is estimated from rock type — a fair guess a geologist could argue with, not a measurement, and the last column says which is which. Earlier versions of this report left those cells blank. That was worse: a blank reads as “nothing is known”, and something is.

Read that way the table stops being a shortlist and starts being a question. On these estimates the Greensand and the Exeter Group hold more, and hold it longer, than the sandstone the whole study is built on — and the limestones drain in weeks. If those estimates are anywhere near right, the rock this study picked is not obviously the best one. Nobody has measured them, and that is the point.

How long a store keeps water, against how much it can hold. Each line is one rock type. Along a line, holding more means draining slower. Between lines, a more transmissive rock gives more volume at the same drainage speed. The shaded band is the speed a store would need if it were to feed a river across a summer.

Finding

Work the leakage and the capacity together and the well-field radius drops out, and so does specific yield. What a store can hold at a chosen drainage speed depends on just two things: the transmissivity of the rock, and how far you may raise the water table. Both enter linearly.

At a 90-day drainage speed — roughly “empties over a summer” — that gives:

Triassic sandstone (T = 122, published) — 0.9 Mm³.
Great Oolite (T = 1,000, estimated) — 7.4 Mm³, eight times as much, needing a 3.4 km field that the 408 km² body has room for.
Chalk (T = 1,400, published) — 10.4 Mm³ in principle, but the 7 km² body here is too small and the wrong shape to hold a 1.5 km field.

So a fast-draining store is not necessarily a small one. It is small in this sandstone. On rock eight times as transmissive the same drainage speed holds eight times the water.

Known unknown

What the rock would actually accept is the largest single uncertainty in this study, and it is not resolved here. What the model does instead is avoid depending on it: no number in this report rests on predicting the rate — where an injection rate is needed a bound is used, and stated.

The three tests

Every option faces the same three tests.

Test	What it asks
1. As built	A scheme switched on in 2010 with empty stores. The record opens on its own driest year, so this is a hard start — and a fair one.
2. Mature	The same seventeen years with stores already full, as for a scheme running a decade. The gap between 1 and 2 is the cost of being new.
3. Six droughts	The three driest years stitched back to back and run twice. Every day really happened; only the order is invented.

Limitation

Test 3 is a stress test, not a forecast. Nothing here claims how likely such a sequence is.

The record all three tests are run on. Every day of it happened. The top panel shows why the resource is hard to catch: it arrives in brief spikes above the take threshold, not as a steady flow. The bottom panel shows why the year you start in matters — the record opens on its own driest year, which is the hard start Test 1 gives every option, and the three red bars are the years Test 3 stitches together.

The one number to hold on to

Every option below is reported the same way, and it is worth fixing what the figure means before meeting it:

The headline measure

Million m³ delivered per drought summer — water put on fields or into low rivers between April and September of a dry year, averaged over the four driest years in the record.

Alongside it sits the percentage of those days on which a survival ration is met — enough to keep a crop alive rather than to grow it well. The volume says how much; the percentage says how reliably.

For scale: the whole area’s licensed agricultural abstraction is about 3 million m³ a year. So an option delivering 1 million m³ in a drought summer is meeting roughly a third of a normal year’s licensed demand at the moment it is hardest to supply.

What is modelled, and what it is built from

A reader entitled to be suspicious should be able to see what is measurement, what is modelling, and what is assumption.

What is measured, what is modelled, and what is assumed. Solid green outlines are measured; plain outlines are modelled from measurements; dashed amber outlines rest on an assumption.

What	Source	How good
Rainfall	77 EA gauges, 2010–2026	Measured
River flow	12 EA gauges, daily	Measured
Terrain	1 m LiDAR	Measured
Geology	BGS mapping and borehole logs	Mapped, interpreted for this study
Rock properties	BGS report WD/97/34	Published, not site-specific
Land use	Crop Map of England 2024	Satellite classification, confidence 0.49
Abstraction licences	EA register, one 100 km² window	Measured, small sample
Moor water levels	Water Level Management Plans	Published, 2009–11 vintage

What turned out not to need modelling

Finding

Demand is not the constraint. Licensed agricultural abstraction is 2.3–3.2 million m³/yr. The water that could physically do good on the arable land alone is about 108 million m³/yr. The licence is under 1% of what would be useful — so no option here is limited by whether anyone wants the water. They are all limited by how much can be caught and kept.

The honest ledger

Real trade-offs — physical, and they will not go away

Trade-off	Why
Big well field vs small	Large fields hold water longer but cost more and may not fit the rock body
Reservoir vs wells	A reservoir is fast and expensive; the ground is slow and cheap
One large site vs several	Several catch more water; each needs its own land, consent and plant
Catching floods vs holding levels	A basin kept empty catches more but is useless as a landscape feature

Model assumptions — choices behind the numbers

Assumption	Value	Effect if wrong
Reservoir realistically buildable	≤5 Mm³	Shifts the balance between surface and underground storage
Rock porosity and transmissivity	Published regional values	Scales every underground number
Leaked water returning to rivers	80%	Tested: changes answers by 1–3%. Not a risk
Settling time before injection	2 days	Sets a minimum basin size, ~0.3 Mm³
Flood depth above channel bed	2 m	The most influential guess here — it decides which sites can fill by gravity

Known unknowns

What the rock will accept when injected. No local precedent — and the model holds that rate fixed across every rock, so a more transmissive body gets no credit for accepting water faster, which is the main thing that would shrink the reservoir in front of it.
Whether injection wells would clog — the usual failure mode of such schemes, and not modelled at all.
Costs. Nothing here is costed. Every comparison is “X delivers more water than Y”, never “X is better value”.

The eight options

Left: delivery in a drought summer, as built and mature. Middle: the six-year drought — the zigzag is the three-year sequence repeating, not a failure pattern. Right: average annual delivery.

Option	Reservoir	As built	Mature	% of days	To rivers	Drought yr 1	Yrs 2–6
A Reservoir only (3 Mm3)	3 Mm³	1.16	1.16	18%	0.00	0.89	0.9–2.7
B Aquifer only, direct injection	0.3 Mm³	1.22	1.26	21%	0.38	3.51	0.8–2.4
C Aquifer + reservoir	5 Mm³	1.90	1.96	32%	0.49	5.75	0.8–2.3
D Three sites, three rivers	2 × 3 Mm³	4.72	5.07	78%	2.51	9.68	4.8–7.1
E Fast rock + slow rock, cascaded	2 Mm³	0.89	0.96	16%	0.50	3.38	0.8–2.3
F Gravity-filled basin	5 Mm³	4.97	5.67	89%	0.99	9.10	2.7–7.1
G Existing flood storage moor	3 Mm³	4.29	4.67	74%	0.81	7.53	2.7–7.1
H The best untested rock	5 Mm³	2.19	2.40	39%	0.39	7.70	0.8–2.3

How to read the option maps

Each option below has a small map. Two conventions run through all of them.

The basin follows the ground. It is drawn as the water surface the terrain would actually hold at that volume, which is why it is never a neat shape. Options F and G are the exception: they are sited rather than screened, and are drawn as a disc of the right area.

The well field is the mound, not a fence line. It is drawn at the radius the model gives it, centred on the nearest suitable rock. Where the mound is wider than the outcrop, that is a real consequence of the modelled radius rather than a drawing error.

The model sizes schemes; it does not site them. So the positions are indicative. The sizes, the radii, which rivers are in play and which rock is being recharged are not.

A · Reservoir only

Component	Specification
Reservoir	3 million m³, about 1 km² at 3 m deep
Aquifer	none
Intake	150,000 m³/day, pumped from the Tone
Supply	40,000 m³/day from basin to fields
Pipework	3.5 km river to basin, plus distribution

**1.16 million m³ per drought summer** — enough to cover **18%** of drought-summer days with a survival ration. A basin caught from the river in winter and drawn down through the summer, with no underground storage at all. It gains nothing whatever from being mature, because it has no memory between years.

Where option A would sit.

Why 3 million m³, and not more. A bigger basin is not a better one: past about 3 Mm³ the extra surface loses more to evaporation than the extra volume stores. This is the answer to the obvious objection that the reservoir was simply built too small.

Real trade-off

Its six-year drought trace is worth a second look: 0.89, 1.33, 2.65, 0.89, 1.33, 2.65. Exactly periodic — year four is identical to year one because nothing carried over. If the objective is resilience across years, surface storage alone cannot provide it at any size this ground allows.

B · Aquifer only, no reservoir

Component	Specification
Reservoir	0.3 million m³ settling pond only
Aquifer	2 km well field in sandstone, ~16 Mm³
Intake	150,000 m³/day, straight to the wells
Injection	150,000 m³/day
Recovery	40,000 m³/day
Pipework	3.5 km river to basin; 2.7 km basin to well field

**1.26 million m³ per drought summer** — enough to cover **21%** of drought-summer days with a survival ration. River water pumped straight down wells with no basin at all. The cheapest thing to build, but it can only take water while the river is high, and it sends barely-settled flood water into the wells — the arrangement most likely to clog them.

Where option B would sit. Well field on A3, 2.7 km from the basin.

Why 150,000 m³/day. With no basin to hold a flood, everything depends on how fast the wells can swallow it — but the curve flattens at 150,000, because beyond that the river, not the wells, is the limit. Spending more on injection buys nothing.

C · Aquifer + reservoir

Component	Specification
Reservoir	5 million m³, ~1.7 km², 2 days settling
Aquifer	2 km well field, ~16 Mm³ capacity
Intake	150,000 m³/day, pumped
Injection	150,000 m³/day
Recovery	40,000 m³/day
Pipework	3.5 km river to basin; 2.7 km basin to well field

**1.96 million m³ per drought summer** — enough to cover **32%** of drought-summer days with a survival ration. The conventional managed-recharge scheme: catch the flood in a basin, inject it underground over the following weeks, pump it back in summer. Better than either part alone, and unlike a reservoir it carries water between years. **This is the baseline everything else should be judged against.**

Where option C would sit. Well field on A3, 2.7 km from the basin.

Two dials, and they trade against each other. More basin substitutes for faster wells and vice versa — the contours run diagonally. But the surface flattens past about 5 Mm³ and 150,000 m³/day, which is where the scheme is specified. Spending on either dial beyond that buys very little.

D · Three sites on three rivers

Component	Specification
Reservoirs	3 × 2 million m³, one per river
Aquifers	3 × 1.15 km well field, ~5 Mm³ each
Intakes	3 × 150,000 m³/day — Tone, Isle/Parrett, Brue/Yeo
Injection	27,000 m³/day per site
Recovery	13,000 m³/day per site
Pipework	3 separate systems — 0.1–3.5 km river to basin; 2.7–11.8 km basin to well field

**5.07 million m³ per drought summer** — enough to cover **78%** of drought-summer days with a survival ration. Three separate schemes of the same kind as C, one on each of three river systems, sharing the same total well capacity. Here the landscape does the design rather than a dial. It works for one simple reason — *the rivers do not flood on the same days*, so three modest intakes are busy more often than one large one.

Where option D would sit. Well field on A3 and A10, 2.7–11.8 km from the basin.

What the map adds

The three sites are not equivalent. All three are modelled on Triassic sandstone, and the only Triassic sandstone in the study area is in the west — so the western site’s wells are 2.7 km from its basin while the two eastern ones are 12 and 20 km away. There is rock beneath the eastern rivers, but it is Greensand and Oolite, and no leakage figure has been derived for either.

D’s strength does not depend on this. It works because three rivers do not flood on the same days, and that stands whatever the rock does. What the map adds is where the cost and the uncertainty sit: either long pipes west, or the first leakage test on an eastern body.

E · Fast rock and slow rock, linked

Component	Specification
Reservoir	2 million m³
Fast store	Great Oolite, 3.44 km mound, 7.4 Mm³, 90-day half-life
Slow store	Upper Greensand, 2.0 km mound, 18.8 Mm³, 6.3-year half-life
Rock	two touching outcrops, both on a river — but both estimated, never measured
Transfer	30,000 m³/day, fast store to slow
Intake	150,000 m³/day

**0.96 million m³ per drought summer** — enough to cover **16%** of drought-summer days with a survival ration. Two genuinely different rocks working together: fractured limestone that drains over a summer to feed the rivers naturally, passing the rest into sand that holds water for years. **Still the worst performer here, and that is the finding.**

Where option E would sit. Well field on A10 and A9, 12.5–16.1 km from the basin.

On the limestone, a store that drains over a summer holds 7.4 million m³ — eight times what the sandstone gives at the same speed. The pairing has the storage it always needed. It still comes last.

Why it fails

Not the rock, and not the plumbing. Look at when the leak happens. A store that half-empties in 90 days is filled by the winter floods and has given most of it back by May. Across the record E returns 0.50 million m³/yr to the rivers. In a drought summer it returns 0.01 — because in a dry year the fast store never filled either.

It feeds the rivers generously in wet years, when they do not need it, and has nothing left in dry ones, when they do. That is this report’s recurring sentence in its sharpest form: a drought is the failure of the winter that would have filled the store. A passive store cannot escape it, because passive means it drains on the calendar rather than on demand.

Would a slower store do better?

The obvious objection, and worth a sweep rather than an argument — because a slower store is not a smaller one. Volume rises in step with the half-life, so asking for 180 days instead of 90 doubles it rather than trading it away. There is no penalty to pay on that axis.

Left: what it delivers to fields, against how big the store has to be. Right: what leaks back to the rivers. The sweep runs from 30 days to three years — a 36-fold range of store size.

Finding

Slower is better for the fields, and the gain is almost nothing. Across the sweep delivery rises from 0.92 to 1.12 million m³ a drought summer — 21% — while the store it needs grows from 2.5 to 91 million m³, a well field 12 km across holding more than most winters produce. Multiply the storage by thirty-six, gain a fifth.

For the rivers there is a real optimum — about 90 days, near enough what the option already uses, feeding 0.21 million m³ over an average summer. In a drought summer it is 0.005 to 0.006 million m³, flat across the whole sweep. No half-life rescues it.

Two further refinements were tried and are kept in the model, off by default: crediting the leak against the day’s river-support release, and holding the fast-to-slow transfer back until the river is too low to abstract from. The first changes almost nothing, because deliberate releases are only 0.02 million m³/yr to begin with. The second moves real water — river baseflow over the record rises from 8.2 to 13.6 million m³, at about 2% of delivery — but not into a drought summer.

F · A basin filled by gravity

Component	Specification
Reservoir	5 million m³ in a natural hollow, ~3 km², under 2 m deep
Filling	gravity through a sluice — no intake pump
Aquifer	2 km well field, ~16 Mm³
Injection	80,000 m³/day
Recovery	40,000 m³/day
Pipework	1.5 km river to basin; 2.3 km basin to well field; return channel to a lower point on the same river

**5.67 million m³ per drought summer** — enough to cover **89%** of drought-summer days with a survival ration. The same scheme as C, but the basin sits low enough that the river fills it through a gate when in flood — no intake pump at all. **The best performer of the eight.**

Where option F would sit. Sited rather than screened, so the basin is a disc of the right area rather than a real footprint. Well field on A3, 2.3 km from the basin.

G · An existing flood storage moor

Component	Specification
Reservoir	3 million m³ held on a moor already used for flood storage — ~10 km² at 0.3 m
Filling	gravity through the existing inlets
Aquifer	2 km well field, ~16 Mm³
Injection	80,000 m³/day
Recovery	40,000 m³/day
Pipework	inlets and pumping station already exist; new pipe is 1.6 km basin to well field

**4.67 million m³ per drought summer** — enough to cover **74%** of drought-summer days with a survival ration. The same idea as F, on ground that is already flooded every winter on purpose. Curry Moor and its neighbours are filled from the river through existing inlets and emptied by an existing pumping station; this option adds injection plant and keeps some of that water instead of pumping all of it away.

Where option G would sit. Sited rather than screened, so the basin is a disc of the right area rather than a real footprint. Well field on A3, 1.6 km from the basin.

H · The best rock nobody has tested

Component	Specification
Reservoir	5 million m³ — identical to C
Aquifer	Upper Greensand, 2 km well field, 18.8 Mm³, 6.3-year half-life
Intake	150,000 m³/day — identical to C
Injection	150,000 m³/day — identical to C
Recovery	40,000 m³/day — identical to C
Pipework	3.5 km river to basin; 12.5 km basin to well field
Confidence	properties estimated from rock type, never measured

**2.40 million m³ per drought summer** — enough to cover **39%** of drought-summer days with a survival ration. Option C moved onto different ground, and nothing else changed. The Greensand is estimated to hold half again as much water as the sandstone and to keep it half again as long — so this is what better rock is worth, with every other dial held still.

Where option H would sit. Well field on A9, 12.5 km from the basin.

Finding

Better rock is worth about a fifth. C delivers 1.96 million m³ a drought summer; H, with 20% more storage held 45% longer, delivers 2.40 — a gain of 23%. Real, and worth having. But the options that reach across the landscape deliver two and a half times C, on the same rock.

So the ranking does not turn on finding better ground. It turns on how much water a scheme can catch. That is worth knowing before anyone spends money looking for a better aquifer.

Confidence

Every number in this option, and in E, rests on a transmissivity and a specific yield inferred from rock type and flagged “guess” in the source data. No leakage has ever been measured on the Greensand. Treat H as an upper bound on what better rock could buy, not as a result: if the estimate is out by a factor of two, so is the answer.

What the three tests show

The cost of being new is real but not fatal. Maturity is worth between nothing (option A) and about 15% (option F). A scheme commissioned in 2010 would have met little of the 2010–11 drought, simply because it had not yet banked anything.

The key finding

The mature store buys about one year. Year 1 of the drought test separates the options widely. From year 2 onward each settles into a pattern set by what it can catch from that year’s flows — options A, B, C, E and H all deliver between 0.7 and 2.6 Mm³ regardless of how much storage they hold, and H holds the most of the five.

Nothing collapses. Even in six consecutive drought years the driest years still carry enough water at high flow that a scheme keeps delivering something. These schemes do not run dry; they run small.

All options side by side

One chart, one question: on a day in a drought summer, is there enough water to keep a crop alive?

Percentage of April–September days in the four driest years on which the scheme delivers at least a survival ration.

Definition

A survival ration here means 2,700 m³/day — roughly a sixth of what is licensed. It is a stated stand-in, not an agronomic finding: there is no crop model here, and the real figure depends on the crop, the soil and the week. Change the threshold and the percentages move; the ordering is what matters.

The chart splits into two clear groups. The five options built on one river cover 16–39% of drought days; the three that reach across the landscape cover 74–89%. Every one is sized at its own best configuration, so the gap is not a sizing artefact.

And the gap survives changing the ground underneath. H is option C on the best rock in the study area, and it reaches 39% — still less than half of what the weakest landscape-scale option manages on ordinary sandstone. The difference is not how much water these schemes store. It is how much they can catch.

The rhythm of each option

A single number per drought summer cannot show when a scheme hands water over, and that turns out to be most of the difference between them. The next two charts put all eight on the same clock.

How to read these

Blue is water going out. The red line is water still in store. Grey behind is rainfall. Both charts share one scale and one clock, and every option is running as a mature scheme.

The pink band at the right is not a forecast. It is the record’s own first three years replayed as if they were the next three, starting the day after the record ends and lined up so the seasons still fall where they should. Each option carries straight on from wherever August 2026 leaves its stores — so the band answers the question a table cannot: if the next three years were like 2010–13, what would this option do?

Options A to D. A’s red line returns to zero every summer and starts each winter from nothing. B, C and D build a store that survives the summer — and note that C’s is still rising in 2024 after fourteen years, which is what “the cost of being new” looks like.

Options E to H, same scale. F and G hold a high store year after year and hand water out on roughly twice as many days as the single-river schemes. E and H sit beside them on the page but behave like the single-river group, which is what they are.

Finding

Every option pushes water out at the same rate — the recovery pump is the ceiling and all of them reach it. What separates them is how many days a year they can push at all: 128 days for A, 259 for F. Not how hard, but how often.

The red lines say why. A’s returns to zero every summer and starts each winter from nothing — it has no memory, so a bad winter is a bad summer with no appeal. F and G still hold 5.5 and 3.9 million m³ on the 30th of September, which is next year’s opening balance.

If the next three years were like 2010–13

Over those three replayed years, A delivers 8.4 million m³ and F delivers 19.5 — on 139 and 253 days a year respectively. The three years include the driest in the record, and the options that arrive at 2026 with water already banked are the ones that get through them.

The same thing shows in how steady each option is from year to year. A’s best year delivers 5 times its worst; F’s ratio is 1.5. That is what “smoothing” means in practice — not a gentler daily curve, but a smaller gap between a good year and a bad one.

What a scheme looks like from the inside

One option in detail, to show the mechanism the table hides. This is C, the conventional basin-plus-wells scheme, over eight years.

Rain and river at the top, the two stores in the middle, water out at the bottom. The reservoir (brown) barely registers — it fills and empties within days. The aquifer (red) is the store that matters: it ramps up through each winter and draws down through each summer, and in the wet run of 2020–21 it reaches about 60% of its capacity. The dashed line at the bottom is all the water that could be put to use, not a requirement; the dotted line is the survival ration the report scores against.

Finding

The basin is a buffer, not the store. Its job is to hold a two-day flood long enough to push it down the wells over the following weeks. Almost none of the water a scheme delivers in August was in the basin in July — it was underground. That is why the reservoir-only option behaves so differently, and why the size of the basin stops mattering above a few million m³.

The same view of the two options that reach across the landscape shows why each of them works, and what each has to respect.

Option D: three schemes, one colour each — solid for the aquifer, dashed for the basin. The dashed lines are the point. The three basins spike at different times, because the Tone, the Isle and the Brue do not flood on the same days; each one is catching floods the others miss. The three aquifers then ride up together and hold. This is the whole argument for spreading a scheme out, and it is invisible in any single number.

Option G has a constraint none of the others do: the moor it would use is not empty ground. It is held to water levels agreed between the Drainage Board, the Environment Agency and Natural England, for farming and for birds.

Option G, drawn in the units its consent is written in. The middle panel is metres of water on the moor, not a percentage, because that is what the Water Level Management Plan regulates. The red line is the moor’s own agreed summer level, 0.30 m above its winter level — the median across 19 structures in the Curry Moor plan of 2011.

A coincidence worth not over-reading

The moor never crosses that line. That is by construction, not by discovery: the option was given 3 million m³ over roughly 10 km², which is 0.3 m, before anyone looked at the plan. What the plan adds is that 0.30 m happens to be exactly the band the moor is already managed through — so this option is asking to use depth that is already consented, rather than asking for more.

That is a reason to look at it and not a reason to assume it is free. The plans set levels by season, and a recharge scheme wants water held at times the plan may not allow. Whether the timing works is a conversation with the Board and Natural England, not a modelling result.

What is worth exploring, and why it works

⭐ Let the river fill the basin itself

Most promising

What it is. A basin sitting low enough that when the river runs high it simply flows in through a gate. No pump. When the flood passes the water drains back to the river, or is pumped underground at leisure.

Why it works. The water arrives in nine bursts a year, two days each. To catch a whole burst by pumping you would need a machine moving 560,000 m³ a day — used nine days a year. A gate costs almost nothing to run and has no such limit.

What would stop it. The ground has to be in the right place: below the river when it floods, above it when it does not. The screen found candidates, but the estimate of flood level behind them is the weakest number in the study.

⭐ Use the moors that already flood

Most practical

What it is. Several moors are already flooded deliberately in winter to protect towns, with inlets and pumping stations built and operating. Also use that water — put some underground before the moor is drained.

Why it works. Most of the cost is already spent. The structures exist, the operating practice exists, and the moors already fill and empty on roughly the right rhythm.

What would stop it. Those moors are managed to agreed levels for farming and for birds, and those agreements would have to be reopened. It needs the Drainage Board and Natural England, not just an engineer.

⭐ Spread across several rivers

Most robust

What it is. Three modest schemes on three different rivers instead of one large one.

Why it works. The rivers do not flood on the same days. Three modest intakes are busy more often than one large one, so they catch about 10% more water for the same total pumping.

What would stop it. Three sites means three lots of land, consent, access and maintenance. The water case is good; the cost case is untested.

Worth knowing about, but not the answer

A reservoir on its own

Water straight down wells, no basin

A fast-draining store feeding the rivers

What this study does not say

It does not recommend a scheme. Costs would decide between these options and none has been estimated.
It does not claim a return period. The six-year drought is a stress test built from real years in an invented order.
It does not predict what the rock will accept. No injection has ever been made here.
Land ownership, designations and consents are unchecked for every candidate site.
Clogging — the most common way such schemes fail in practice — is not modelled at all.
The survival threshold is this study’s own, not an agronomist’s.

What the next steps would be

Survey river levels at the candidate basins. Cheap, quick, and it decides whether the best-performing option is real.
Talk to the Drainage Board about the flood-storage moors. If they can double as recharge basins, most of the capital is spent.
Cost the options. Wells against earthworks is the trade that decides this.
Do one injection test. It would remove the largest single uncertainty in the study.

Somerset Levels & Vale of Taunton feasibility study, version 2 · 13 August 2026. Sources: Environment Agency hydrology and abstraction data; British Geological Survey mapping and report WD/97/34; Defra Crop Map of England 2024; Somerset Drainage Boards Consortium Water Level Management Plans; OpenStreetMap contributors. Every figure is reproducible from raw data with a single command.

Where every number comes from

Every figure above is produced by a background chapter, and every chapter regenerates from raw Environment Agency, BGS and Defra data with one command. They are working documents rather than prose, and they sit behind this report rather than beside it.

The background chapters — all forty-one, grouped by layer: the water, the rock, the demand and the scheme.
Earlier versions — the drafts this report grew out of, and the corrections between them.

Earlier versions

2026-08-13T00:00:00.000Z

The current report is Banking winter water for a dry summer, version 2. These are the drafts behind it, kept because the corrections between them are part of the record rather than something to tidy away.

Banking winter water for a dry summer (version 1) — The first version of the summary report, circulated 12 August 2026. Superseded by version 2, which corrects two figures and adds an eighth option.
FloodMAR Somerset — scheme assessment (v2) — The scheme assessment the report grew out of, with every parameter marked measured, published, derived, placeholder or assumed.
Storing winter river water underground on the Somerset Levels — The first full paper. Predates the scheme layer entirely.
Flood-water capture and aquifer storage on the Somerset Levels — The water-accountancy working note: what the model is, what it can say, and what it cannot.

← Back to the report

Known issues, deferred features and architectural TODOs

2026-08-12T00:00:00.000Z

A live register: issue, context, priority, and the prompt it belongs in. Items are removed when resolved.

ARCHITECTURAL / DATA MODEL

A1 — School hierarchy is one level too flat

Issue: UK Schools currently acts as both a country grouping AND a specific institution. A school admin assigned to “UK Schools” sees all projects under it, which is wrong when multiple UK schools are in the system. Should be: LFTI root → Country grouping (UK Schools) → Specific school (Bristol Academy) → School admin scoped to their school only. Fix: Add one hierarchy level. System admin creates specific school nodes. Visibility scoping matches institution_id to specific school node, not country grouping. Priority: High — must fix before any real schools are onboarded. Context: Discovered during project setup testing with ukadmin.

A2 — parent_id is singular but relations[] expresses multi-parent

Issue: The node schema has a single parent_id for tree rendering, with multi-parent expressed via contains relations. This means a node that genuinely belongs to multiple projects only appears in one place in the tree. The other relationships are only visible in graph mode. Current behaviour: Correct and intentional for now. Tree view is one lens. Risk: Interchange nodes (sessions involving two institutions) will need careful handling — their parent_id should point to whichever institution initiated, with involves relations to the other. This discipline must be maintained. Fix when: Interchange nodes are built. Add a note in the interchange prompt to enforce this. Priority: Medium — document the convention clearly, enforce in interchange prompt.

A5 — Person nodes not attached to institution/project tree

Issue: All person nodes (dev seed users, wizard-created staff, class nodes) are currently root-level or loosely attached. They appear in the tree alongside LFTI and UK Schools which is wrong and will become confusing at scale. Should be: Person nodes sit under their most appropriate parent in the tree — institution node for staff/admins, class node for students, project node for facilitators. parent_id must be set correctly, not null. Fix: When creating person nodes via auth seed, project wizard, or manual capture — always set parent_id to the correct parent. Dev seed users should be reparented: system-level users to inst_lfti, institution-specific users to their institution node. Priority: Medium — fix in the same prompt as F21 (class roster) since that prompt creates person nodes properly anyway. Context: Identified during multi-user tree view testing. Issue: The filterNodesByVisibility() function uses a simplified institution_id match rather than full graph traversal (walking contains chains up to find which institution a node belongs to). Current behaviour: Works correctly for directly tagged nodes. May miss nodes that inherit visibility from a parent without an explicit institution_id in their own meta. Fix: Implement recursive parent traversal in filterNodesByVisibility(). Check meta.institution_id on the node first; if absent, walk parent_id chain until an institution node is found. Priority: Medium — needed before multiple real institutions are using the system simultaneously. Context: Noted in auth prompt as deferred.

A4 — Partners visibility rule not fully implemented

Issue: The _visibility: "partners" rule is defined (visible to institutions connected via involves or responds_to relations) but only a simplified version is implemented. Full graph traversal to determine partnership is deferred. Fix: When interchange nodes are built, implement the full partners check: a user can see a partners node if their institution_id has an involves or responds_to relation to any ancestor of that node. Priority: Medium — needed for interchange feature. Context: Noted in auth prompt as deferred.

FEATURES DEFERRED TO LATER PROMPTS

F1 — Tool selection UI

Issue: Phase nodes currently show a nudge toward the reference tool library but have no guided tool selection flow. Should be: Filter-based tool cards (individual/group, indoor/outdoor, sync/async etc), select 1–3 tools, progress to next phase. Three selected triggers a move-on prompt but fewer is allowed. Priority: High — next major feature after project setup. Prompt: tool-selection-prompt.md (to be written)

F2 — Session flow and artefact capture

Issue: No UI for students to actually run a tool session and upload/create artefacts within a phase. Should be: Group selects a tool, runs the session, uploads artefacts as block nodes (images, text, drawings). Soft limit of 5 contributions per group per phase as a nudge. Priority: High — core student-facing feature. Prompt: session-flow-prompt.md (to be written)

F3 — Approval flow (async and live session mode)

Issue: Approval mode is set during project setup but the actual approval UI is not built yet. Should be:

Standard (async): teacher sees a list of pending contributions, approves or flags with a note
Live session mode: real-time feed of contributions, large approve button, designed for whiteboard display
Flagged content returns to group with a note Priority: High — needed before any content is shared externally. Prompt: approval-flow-prompt.md (to be written)

F4 — Project dashboard Phase 3

Issue: Project dashboard (overview tab with progress grid, needs-attention items, upcoming sessions) not yet built. Phase 1 and 2 of project setup complete but dashboard is Phase 3. Should be: Progress grid showing contribution counts per phase, needs-attention notifications, participant summary, upcoming workshop dates. Priority: High — next step after current phase. Prompt: project-setup-prompt.md Phase 3 (continuation)

F5 — Observer project overview page

Issue: Observer role currently sees the same tree view as other users. Should have a dedicated read-only view. Should be: A clean page showing past and live projects with status indicators and approved Present artefacts only. No access to working nodes. Natural home for light analytics. Priority: Medium — needed before funders/external observers are given accounts. Context: Identified during multi-user testing.

F6 — Collaborative prioritisation tools UI (Stones in Circles etc)

Issue: Collate phase tools like Stones in Circles, Matrix Ranking, Pairwise Ranking are defined in the reference instance but have no interactive UI. Should be: Facilitator-run single-screen tool for stones/voting, matrix, pairwise. Student-facing display. Output saved as a prioritisation artefact node. Priority: Medium — needed for Collate phase sessions. Prompt: collate-tools-prompt.md (to be written)

F7 — Synthesis canvas placeholder

Issue: The Synthesis node in the Collate phase is explicitly marked as a placeholder. No collaborative drawing/compositing surface exists. Should be: A shared canvas where groups can produce a collective representation from Gather artefacts. This is the most technically complex piece of Collate. Priority: Low — deferred intentionally. Placeholder node exists. Do not build until Gather and basic Collate are working well. Context: Noted in PLA_TOOLS_REFERENCE.md.

F8 — Body Map facilitation protocol

Issue: Body Map tool node is marked _status: protocol_pending. Full facilitation protocol needs to come from Mary Manzole (Kamoto Artistic Director). Action required: Conversation with Mary Manzole to document the protocol. Update the Body Map node body with the authoritative facilitation notes. Priority: High — do not run Body Map sessions without this protocol documented. Context: Noted in PLA_TOOLS_REFERENCE.md.

F9 — Transect walk spatial data (GPS variant)

Issue: Transect walk currently supports low-tech (hand-drawn path, image upload). GPS-tagged high-tech variant is defined but not built. Should be: Optional GPS track on a transect walk contribution node. Geotagged observation points. Display on a map view. Priority: Low — secondary option, hand-drawn is primary. Context: Identified in Gather/Collate design discussion.

F10 — Student voting on tools

Issue: Students can see the tool library but cannot signal which tools they want to use. Should be able to vote/react without unilaterally adding a tool to the project. Should be: A reacts relation type. Student node reacts to a tool node with meta.reaction: "want_to_use". Facilitator sees these as requests on the phase node. Extension: Class-level collation of votes — the votes themselves go through a mini Collate process before the facilitator makes the final selection. Self-referential — the methodology for choosing tools is itself participatory. Priority: Medium. Context: Identified during reference instance visibility discussion. Class collation layer added during Phase 3 review.

F18 — Group instance nodes

Issue: No group instance node type exists yet. Group instances should be children of a tool instance node, carrying: member names and roles, modality (digital/paper), status (not started / in progress / submitted / uploaded by proxy). Should be: The facilitator view of a tool instance shows all group instances and their current state at a glance — who has submitted, who is paper-only, who hasn’t started. Priority: High — needed before any real sessions run. Context: Identified during tool instance design discussion.

F19 — Coordinate clustering for digital transect walk collation

Issue: When multiple group instances have image map annotations near the same coordinates on a shared reference image, the Collate view should surface this as a cluster with a frequency count — nudging toward the deduplication conversation without forcing it. Important constraint: This ONLY applies to digital image maps with shared pixel coordinates. Hand-drawn transects and maps cannot be clustered algorithmically — the reconciliation is a human participatory activity (see F23). Priority: Medium — needed for digital Collate phase of transect walk tool. Context: Identified during tool instance design discussion.

F20 — Contribution body + location as relational finding

Issue: The image map pin captures the where; the contribution body captures the why-it-matters. The Collate view should display both together for each cluster — not just “12 groups marked this point” but “here is what they said about it.” Should be: In the Collate surface, each coordinate cluster shows: frequency count, all group names that marked it, and all contribution bodies attached to those annotations, readable side by side. Priority: Medium — the essence capture surface for transect walk collation. Context: Identified during tool instance design discussion.

F21 — Class roster management

Issue: No formal class roster exists. Students are either person nodes added manually or not in the system at all. Group management cannot work properly without a class list. Should be: Lightweight person nodes for students — first name + last initial minimum (Tom P), no login required. Teacher enters roster via class node (paste or type list). Roster entries matched to full user accounts if student later gets one. Absent students markable per session, reversible. Priority: High — needed before group management (F22) works. Context: Identified during group management design discussion.

F22 — Group management view

Issue: No UI exists for assigning students to groups within a tool instance. Should be: Pre-Start view within a tool instance showing class list on one side, groups on the other. Every student starts unassigned. Teacher (or students) assigns to groups. View shows: unassigned students highlighted, groups with missing roles flagged, absent markers. Must be completable in under 5 minutes for a class of 30. States: unassigned / in group no role / in group with role / absent / arrived late (addable mid-session). Priority: High — needed before real sessions run. Context: Identified during group management design discussion.

F23 — Map Reconciliation as a Collate tool

Issue: Hand-drawn maps from Gather cannot be algorithmically clustered. The reconciliation of multiple hand-drawn maps into one agreed reference map is itself a meaningful participatory activity. Should be: A specific Collate tool instance type — “Map Reconciliation” — where input is a collection of hand-drawn map/transect images from Gather and output is a collaboratively produced single reference image. Groups compare drawings, negotiate what counts as the same place, produce an agreed version. Priority: Medium — add to reference instance tool library when Collate tools are built. Context: Identified during transect walk collation discussion.

F24 — Student group assignment and contribution permissions

Current state: Students are read-only — no “+ Add contribution” buttons visible at any level. Facilitator/admin can add contributions at tool instance level (class example) and to any group instance. This is an acceptable interim state for facilitator-led sessions. Problem: Without knowing which group a student belongs to, the system cannot grant contribution rights to their group only. Granting rights to all groups is too permissive. Three options:

Option A — Proper student accounts linked to group membership (long term) Students have login credentials. User record links to person_node. Person_node is a member of a specific group_instance. System knows who they are and what group they belong to. Requires F21 (class roster), F22 (group allocation), and F12 (invite/account creation). Also requires a safeguarding/data protection framework for creating accounts for minors.

Option B — Adhoc group token login (recommended interim) No individual student accounts needed. Each group_instance gets a short token/PIN (e.g. “GROUP1-X7K2”) printed on the group’s worksheet (F15). Any device entering that token gets group-scoped permissions for this tool instance — can add contributions to that group only, see that group’s work, nothing else. Token expires when tool instance is completed or manually invalidated. No email, no password, no personal data stored. Maps naturally onto the printable worksheet.

Option C — Hybrid (long term) Students with accounts get full individual identity and proper group assignment. Students without accounts use a group token as lightweight fallback. Both work simultaneously.

Recommended path: Build Option B alongside F15 (printable sheet) — the group token prints on the worksheet naturally. Option A/C follows when a data protection framework for student accounts is in place. Priority: High — needed before real student-facing sessions run. Context: Identified during contribution permission review. Issue: Current implementation adds tool references to a phase node but does not create a tool instance node as a child. The instance is where the live facilitation plan, session steps, timing, materials, and contributions should live. The reference tool node is the canonical definition; the instance is the running version for a specific class on a specific day. Should be: Selecting a tool creates an instance node (type: tool_instance) as a child of the phase node, with a references relation to the source reference tool node. The instance node inherits the facilitation steps from the reference as a starting point, which the facilitator can edit. Contributions attach to the instance, not the phase node directly. Priority: High — needed before real sessions run. Current contribution attachment to phase node is a temporary structure. Context: Identified during Phase 3 tool browser review.

F14 — Tool flow suggestions (greying/highlighting based on prior selections)

Issue: No recommendation layer exists to guide facilitators toward tools that complement what has already been selected in earlier phases or movements. Should be: When browsing tools for a phase, tools that flow well from previously selected tools are subtly highlighted. Tools that would be redundant or clash are subtly greyed. Based on feeds and sequence relations between reference tool nodes — data already exists in the graph, just not surfaced. Example: Body Map selected in Past→Gather → Story Circle and River of Life gently highlighted for Situation→Gather. Venn Diagram actual/ideal highlighted for any →Collate phase following a narrative Gather tool. UI pattern: Subtle — a small compatibility indicator on each card, not a hard block. Facilitator’s judgment always overrides. Priority: Medium — valuable but not blocking. Build after tool instances (F13) are working. Context: Identified during Phase 3 tool browser review.

F11 — Academic calendar display

Issue: Session dates are stored as ISO UTC. Display should be localised to each institution’s academic calendar (UK terms, NZ terms, Zambian school year). Current behaviour: Dates display as ISO or generic format. Fix: Add calendar localisation layer. Institution node carries meta.academic_calendar. Display layer translates ISO dates into the right term/week framing for each user’s institution. Priority: Medium — needed when multiple countries are running simultaneously.

F12 — Invite system for staff and students

Issue: Staff and student emails are stored in person node meta during project setup but no actual invite is sent. Should be: Email invite with a link that creates their account and associates them with the correct institution and project automatically. Priority: Medium — currently requires manual account creation by system admin. Context: Noted in project setup prompt as placeholder.

UI / UX BUGS

U1 — Wizard tab state loss on step switch

Issue: If a user enters details on the Schedule step (e.g. specific dates) then switches to another step and back, their edits are lost. Fix: Store wizard form state in a persistent local object rather than reading directly from DOM inputs on step change. Read from the object, write to it on every input event. Priority: Low — minor UX issue, doesn’t affect functionality. Context: Identified during project setup testing.

U2 — Student delete permissions too broad

Issue: Delete button is hidden for student role globally, but students should be able to delete nodes they themselves created (e.g. their own contribution block nodes). Fix: Check both role AND whether node.meta.created_by === state.currentUser.id before showing/hiding delete. Students can delete their own; cannot delete others’. Priority: Medium — before student-facing sessions go live. Context: Identified during multi-user testing.

U4 — Reference tool filter editor missing existing value picker

Issue: The filter tag editor on reference tool nodes shows current values as removable pills and a free-text “add value” input, but there is no way to see and select from existing values already used by other tools for that filter type. A facilitator adding “playing fields” to location has no way to know if another tool already uses “playing_fields” (underscore) vs “playing fields” (space) — leading to inconsistent values and broken filtering. Should be: The “add value” input should show a dropdown of existing values for that filter type (derived from all tool nodes’ meta, as per the filter pill source-of-truth fix) as the user types — a typeahead/autocomplete. Selecting an existing value ensures consistency. Free text entry still allowed for genuinely new values. Priority: Medium — important for filter consistency before many tools are edited. Context: Identified during filter editor review after Piece 1.

U5 — Reference tool filter tags layout is purely vertical, too long

Issue: Filter tag groups (format, location, modality, duration, tech_level) stack vertically, causing the tool node content section to scroll excessively. Each filter type takes a full row even when its values would fit inline. Should be: Filter tags laid out horizontally — filter type label followed by its value pills on the same row, wrapping only when necessary. Multiple filter rows should fit in one or two visual rows total rather than five separate vertical blocks. Compact, scannable, not overwhelming. Priority: Low — cosmetic but affects usability of the tool editor for anyone editing multiple tools. Context: Identified during filter editor review after Piece 1. Issue: As the node tree grows with multiple projects and reference tools, the left panel tree may become unwieldy. No virtual scrolling or lazy loading implemented. Fix: Consider collapsing all but the active project by default. Lazy-load children on expand rather than rendering the full tree on load. Priority: Low — not a problem yet, will become one at scale.

SECURITY / ACCESS CONTROL

S1 — No enforcement of reference node read-only status

Issue: Reference nodes (_level: reference) are currently editable by all authenticated users. This is intentional during development but should be locked down before real schools are onboarded. Fix: In save/delete handlers, check meta._level === 'reference' and require superadmin role to edit. Show read-only styling for all other roles (already partially implemented visually). Priority: Medium — before onboarding real institutional users. Context: Intentionally left editable for development convenience.

S2 — No HTTPS

Issue: Running on HTTP locally. Cookies marked secure: false for development. Must enable HTTPS before any deployment beyond local dev. Fix: Add SSL certificate (Let’s Encrypt for self-hosted, automatic on most cloud platforms). Uncomment secure: true on cookie settings in api/auth.js. Priority: High — before any external deployment. Context: Noted in auth prompt with a comment in the code.

S3 — No rate limiting on auth endpoints

Issue: Login endpoint has no rate limiting. Vulnerable to brute force attacks. Fix: Add express-rate-limit to the login route. 10 attempts per 15 minutes per IP. Priority: Medium — before external deployment.

CONTENT / METHODOLOGY

C1 — Several PLA tool nodes have thin content

Issue: Some tool nodes in the reference instance have brief descriptions rather than full facilitation notes. River of Life, Timeline, Peer Interview, Hot Seating, and Story of Self in particular need richer body content. Fix: Expand body text for these nodes. Draw from the source documents in the project (EQUINET toolkit, AFCAP slides, Episcopal Relief transect walk guide). Priority: Medium — before facilitators are using the reference instance as a planning resource.

C2 — No facilitation notes for Present phase tools

Issue: Present phase tool nodes (Short Video, Podcast, Zine, Social Channel) have descriptions but no facilitation guidance. Fix: Add practical facilitation notes — equipment needed, how to brief students, common pitfalls, time estimates. Priority: Medium.

C3 — Cross-cohort tool variants not fully documented

Issue: Several tools have cross-cohort variants described in PLA_TOOLS_REFERENCE.md (transect walk as cross-cohort presentation, body map comparison, river of life side-by-side) but these variants are not yet represented as separate nodes or documented as facilitation options within the tool nodes. Fix: Add variant block nodes under relevant tools, or expand tool node bodies with cross-cohort variant sections. Priority: Low — needed when interchange feature is built.

Participatory tools — reference instance content

2026-08-12T00:00:00.000Z

The source of truth for seeding the reference instance node tree. Each tool becomes a node; each section heading a phase or category. Provenance is preserved throughout, because methodology origins matter.

PRINCIPLES & ETHOS

(Meta-level — governs how all tools are used)

These are not tools. They are the conditions under which tools work. A tool used without these principles produces data. A tool used with them produces understanding.

Handing Over the Stick

Origin: Robert Chambers, PRA tradition What it means: The facilitator’s job is to give up control of the process as quickly as possible. The moment the facilitator holds the pen, marker, or stone, they own the output. The goal is to place those instruments in the hands of participants as soon as the activity is understood. In a school context: the facilitator is not the teacher. The student holds the pen. Watch for: Facilitators who “help” by writing, drawing, or arranging on behalf of participants. This is the most common way the methodology is undermined.

Triangulation

Origin: PRA/PLA tradition, Robert Chambers What it means: No single tool, source, or analyst tells the whole story. Use multiple methods (methods triangulation), ask the same question of different people (source triangulation), and have different people analyse the same data (analyst triangulation). When findings converge across methods and sources, you can have more confidence. When they diverge, that divergence is itself important information. In LFTI: The pre-perceptions instrument, the body map, and the transect walk should produce overlapping and sometimes contradictory stories about the same students’ experience. The contradictions are data.

Sitting Down

Origin: PRA field practice What it means: Literally and metaphorically. The outside facilitator positions themselves physically below or level with community members — sitting on the ground, not standing at a flipchart. In a school context this is radical: adults stand, students sit. Reversing this changes the power in the room immediately. Even moving from behind a desk to sitting in a circle changes what is possible. Watch for: The facilitator who stands while students sit. The adult who controls the front of the room. The arrangement of furniture that recreates the classroom hierarchy inside what is supposed to be a different kind of space.

Optimal Ignorance

Origin: Robert Chambers, PRA tradition What it means: You do not need to know everything. You need to know enough to act usefully. Trying to be comprehensive produces paralysis and positions the facilitator as the one who must understand before the community can proceed. Accept that you will not understand everything, that some things will remain opaque, and that this is fine. In LFTI: A facilitator going into a Zambian classroom does not need to fully understand the Zambian education system before beginning. What they need is enough humility to listen well.

Offsetting Biases

Origin: PRA/PLA tradition What it means: In any group, some voices are structurally more likely to be heard: older, male, confident, fluent in the dominant language, higher status. Participatory methodology requires actively seeking the voices that the room is not designed for. This means disaggregating groups by gender, age, confidence level. It means asking who is not speaking and why. It means creating conditions — anonymity, drawing, movement — where those without verbal confidence can still contribute. In LFTI: Who speaks in a UK classroom? Who speaks in a Zambian classroom? Who never speaks? The methodology must be designed to reach the student who has learned that their voice is not wanted.

Facilitation Not Extraction

Origin: PLA/community development tradition What it means: You are not mining data from people. You are enabling people to reflect on and articulate what they already know. The process has value independent of any output it produces. A student who has mapped their school, told a story about their body, and ranked what matters to them has done something for themselves — not just for a researcher. Watch for: Treating students as data sources rather than as the primary beneficiaries of the process. Rushing to outputs without allowing reflection time. Taking the artefacts away without leaving copies with the participants.

The Body as Instrument

Origin: Theatre for Development / Augusto Boal / Kamoto Community Arts What it means: Knowledge that cannot be spoken can be performed. Movement, gesture, posture, and voice carry meaning that survives translation across language, age, and culture. When a student cannot find words for their experience of school, they may be able to show it with their body — in a frozen image, a walk, a sound, a gesture. This is not a lesser form of knowledge. It is often a more honest one. In LFTI: The body is the first instrument available to every student in every context, regardless of literacy, language, or resources. Kamoto’s methodology is built on this. It is why performance, image theatre, and the body map are core tools, not optional extras.

The Rehearsal for Reality

Origin: Augusto Boal, Theatre of the Oppressed What it means: Theatre and performance provide a protected space to try out what cannot be tried in ordinary life. A student can play the headteacher. A Zambian student can play a Bristol student. The role distance is both protective (you are not speaking as yourself, so you are safer) and generative (you discover things in role that you did not know you knew). The rehearsal is not a simulation — it is a form of genuine exploration.

Insider Knowledge is Primary

Origin: Action Research / Participatory Action Research tradition What it means: The researcher is not more expert than the researched. The student is the expert on their own experience of school. The facilitator’s job is to create conditions in which that expertise can be expressed, examined, and acted upon — not to interpret it, correct it, or replace it with academic knowledge. The student’s account of what school is like is primary data. It is not anecdote.

Reflection-Action Spiral

Origin: Action Research / Kurt Lewin / Paolo Freire What it means: You do not plan completely, then act, then evaluate. You act, reflect on what happened, replan, act again. Each cycle of Gather→Collate→Present is one turn of this spiral. The output of Present is not the end — it is the input to the next Gather. Understanding deepens through iteration, not through increasingly comprehensive planning. In LFTI: The three movements (Past, Situation, Futures) are three turns of the spiral. The Whole cycle is a fourth turn that reflects on all three.

Ethical Practice

Origin: Research ethics / child safeguarding / participatory traditions What it means: Several non-negotiable principles govern all LFTI activities:

Informed consent — participants (and for minors, guardians) understand what they are doing, what will happen to their contributions, and can withdraw at any time.
Do no harm — no activity should leave a participant in a more vulnerable position than before. This includes emotional harm from activities that surface difficult memories without adequate support.
Anonymisation — student stories and artefacts are anonymised by default unless a student explicitly chooses to be named.
Image rights — photographs, videos, and body maps involving students require specific consent. Copies belong first to the participant.
The camera warning — cameras and recording devices change the dynamic of a room. Use with caution, use with consent, use sparingly.

GATHER PHASE TOOLS

Pre-perceptions Instrument

Origin: Green Living Movement (Emmanuel Mutambashiku), Zambia Phase: Gather (runs twice — once at start of whole project, once after exchange) Format: Individual, silent. A4 paper folded into four quadrants. Time: 15–20 minutes each instance

The four quadrants:

What I think of myself (as a learner, a young person, someone from this place)
What I think of them (students in the other countries, before knowing them)
What I think they think of me
What I think they think of themselves

Process: Completed individually and in silence before any introduction or context-setting. No discussion during. Facilitator collects — or students keep and bring back. Run again at the end of the full exchange. The delta between first and second instance is the primary evaluation measure.

Critical rule: Do not explain, correct, or discuss responses during the first instance. The pre-perception must be genuinely pre. Any framing before the instrument contaminates it.

Feeds into: Whole cycle → Gather (second instance), Present (delta reveal as evaluation artefact)

Note: This tool runs across the whole project, not just one movement. It is a Gather tool in structure but an evaluation instrument in function.

Observation

Origin: PRA/PLA tradition (AFCAP, Chambers) Phase: Gather Format: Individual or paired, with notepad. Can be structured (specific things to look for) or unstructured (open observation). Time: Flexible — from 10 minutes to a full session

What it captures: People, resources, spatial dynamics, power indicators, movement patterns, what is visible vs hidden, what is named vs unnamed.

In a school context: Who moves freely through the school? Who is confined? Where do students go when they have choice? Where are the unofficial gathering places? What does the staffroom door communicate? What is on the walls, and who put it there?

Facilitation note: The facilitator observes alongside participants, not instead of them. Participants are observing their own environment — they are the experts. The facilitator’s role is to provide a prompt and hold the time.

Low-tech: Notepad and pencil. High-tech: Phone camera, voice memo, annotated photograph.

Semi-structured Checklist Interview

Origin: PRA/PLA tradition (AFCAP) Phase: Gather Format: Individual (key informant) or group (focus group). Two facilitators recommended — one to facilitate, one to note. Time: Individuals: 45–60 minutes. Groups: 90–120 minutes.

Key features:

A checklist of topics, not a questionnaire. The order is flexible.
Open-ended questions only: What? Why? When? Who? How? Where?
The interviewer follows the interviewee’s direction — unexpected topics are welcomed.
Key informant variant: for those with specific expertise (a teacher, a caretaker, a school governor).
Focus group variant: for groups with shared experience (a year group, a friendship group, students who travel far to school).

In LFTI: Semi-structured interviews with teachers are a specific variant — the teacher as key informant on the system they operate within, not as an authority figure. The semi-structured format protects against the interview becoming a defence of current practice.

Facilitator note: The interviewer’s job is to be genuinely curious. If you already know what you think the answers are, you will not hear what is actually being said.

Transect Walk

Origin: PRA/PLA tradition (AFCAP, Episcopal Relief & Development, Chambers) Phase: Gather Format: Small groups (pairs or up to 8). Multiple routes can run simultaneously. Time: 1–3 hours including debrief

Description: A structured observational walk between two points, crossing as many different zones of the school/community as possible. The walk produces a diagram — hand-drawn, with annotations — that becomes the primary artefact.

Facilitation steps:

Route planning — choose a transect that crosses maximum diversity of zones (classroom, corridor, playground, entrance, boundary, off-site)
Introduction — share the purpose and focus (e.g. “we’re looking at where students have and don’t have voice”)
Walk — stop at zone transitions. Ask: What do you see? Who do you see and what are they doing? What happens here that doesn’t happen elsewhere? What is missing here?
Talk to people along the way — brief, informal, genuine curiosity. Not an interview — a conversation.
Draw as you go — one person in each group sketches the route and marks features. The sketch is intentionally rough. Relative scale (what is drawn larger) is information.
Zone debrief — after the walk, compile the diagram. Identify distinct zones. What characterises each? What assets, problems, opportunities are in each zone?

Low-tech: Paper, pencil, chalk on ground for the debrief diagram. High-tech variant (secondary): GPS track, geotagged photos, digital annotation on a base map. This is a secondary option — the hand-drawn version is primary because the distortions in hand-drawn maps are data.

The distortion principle: A student who draws the playground three times bigger than the classroom is telling you something about where they feel alive. Do not correct the scale. Preserve it.

Pairs to gallery: Ten pairs produce ten transect diagrams. In Collate, these ten diagrams are displayed together. What is consistent across all ten? What is idiosyncratic? The collection is the data.

As presentation: The transect walk can itself be the presentation — participants lead others (community members, other cohorts, decision-makers) along the route, narrating what they found. The walk is the report.

Body Map

Origin: Kamoto Community Arts / Mary Manzole (Artistic Director, Kamoto) Phase: Gather (primary — Past movement). Can extend to Situation and Futures. Format: Pairs, then individual, then gallery sharing. Time: 2–3 hours including gallery and discussion Materials: Large paper (A1 or larger — wallpaper, flipchart sheets joined), chalk (if on floor/ground), markers, pens, paint if available.

Description: One person lies on the paper while their partner traces the outline of their body. The outline becomes a map. The maker then fills their body map with stories, memories, feelings, and images placed on the part of the body where they feel that thing lives.

Examples of what might be placed:

A broken arm from childhood riding a horse — placed on the arm
Grief for a grandmother — placed in the hair, or the chest, or wherever it lives for this person
Anxiety about exams — placed in the stomach
Pride in running — placed in the legs
A song learned from a parent — placed in the throat or the ears
A journey — placed in the feet

The spatial placement is the analysis. You do not describe where something lives — you show it. Where people place things is not arbitrary. The body knows things that language doesn’t always reach.

Facilitation steps:

The tracing — in silence. The person being traced lies still. The tracer is careful and attentive. This act itself is significant — being carefully attended to is not a common experience.
Individual mapping — each person fills their own outline alone, working from inside the boundary someone else drew for them. No instruction about what to include — only the prompt: “place what you want to share, where it lives in your body.”
Gallery — maps are displayed. The group walks the gallery in silence first. No explanations yet.
Sharing — makers can choose to share what they’ve placed, or not. Nothing is compulsory.
SHOWED analysis — group discussion: What do you see? What is happening in these bodies? How does this relate to our lives? Why are these stories here? What can we do?

Cross-cohort power: A UK student’s body map alongside a Zambia student’s body map, displayed without captions. The viewer can see before reading: what stories do these two bodies share? Where do they diverge? The chest full in one and empty in another. The feet loaded in one, light in another.

IMPORTANT — Facilitation note: This tool surfaces personal and sometimes painful material. It must be facilitated by someone who knows how to hold that space — not just manage an activity. Mary Manzole’s facilitation protocol is the authoritative version for LFTI. This node is a placeholder until that protocol is documented in conversation with Mary. Do not use this tool without adequate facilitation preparation.

Ethical note: Body maps are personal and may be intimate. Explicit consent is required before displaying or photographing them. The map belongs to its maker. Copies stay with participants.

Photo Walk / Participatory Photography

Origin: PhotoVoice methodology (Wang & Burris, 1997) / Participatory Photography tradition Phase: Gather Format: Individual or paired. Camera/phone distributed or participants use own devices. Time: 45–90 minutes walk + 30–60 minutes SHOWED analysis

Description: Participants are given a prompt and asked to photograph their school/community in response. The prompt should be open: “photograph what matters to you about this place” or “photograph what school feels like” or “photograph what you wish others could see.”

The photograph as framing device: Giving someone a camera is giving them the power to say “this is what I want to look at.” What students choose to photograph — and what they choose not to — is the data.

SHOWED analysis:

S — What do you See in this photograph?
H — What is Happening here?
O — How does this relate to Our lives?
W — Why does this situation exist?
E — What can we Do (Educate, Empower, Act)?

Exhibition as presentation: The photographs become an exhibition. This is a complete Gather → Present pathway without a formal Collate stage — the curation of which photographs to display is the collation.

Ethical note: Photography in schools requires consent. Photographs of identifiable students require specific consent. Photographs of staff require consent. Who appears in an image, and who is conspicuously absent, is itself a finding.

Story Circle

Origin: Oral history / narrative methodology / community organising Phase: Gather Format: Small groups of 4–8. Seated in a circle, no hierarchy. Time: 45–90 minutes

Description: Each person tells a brief story in response to a prompt. No interruptions. No questions during. After all stories are told, the group finds the common threads.

Prompts for Past movement:

“Tell a story about a moment when you felt like a learner — really learning — not necessarily in school.”
“Tell a story about a time school felt like it was made for someone else.”
“Tell a story about something you know that school didn’t teach you.”

The no-interruption rule is structural. It prevents the loudest voice from shaping the story while it’s being told. Responses come after, in the thread-finding.

Thread-finding: After all stories: “What did we hear in common? What surprised you? What was different?” The facilitator does not lead this — they open it and step back.

River of Life

Origin: PLA/narrative methodology Phase: Gather — Past movement specifically Format: Individual drawing, then paired sharing, then gallery. Time: 45–60 minutes

Description: Draw your life as a river. The river has tributaries (people and experiences that fed into you), rapids (difficult times, turbulence), still pools (peaceful or formative times), waterfalls (sudden transformations or losses), and a current direction (where the river is going now).

The spatial metaphor does work that prose cannot: You do not decide in advance what is a rapid and what is a pool. The drawing decides. Students who have never told anyone about a difficult period of their life will draw rapids and then, looking at what they’ve drawn, find language for it.

Cross-cohort version: Rivers from three countries displayed together. Where are the rapids? Do they cluster at the same life moments (exam periods, transitions between schools, family disruptions) or at different ones? The comparison is the learning.

Peer Interview

Origin: Participatory Action Research / oral history Phase: Gather Format: Pairs, rotating roles. Each person is both interviewer and interviewee. Time: 20–30 minutes per direction

Description: Structured interview between students, using a checklist (not a questionnaire). The horizontal relationship between students (as opposed to adult-to-student) changes what is possible. Students often tell each other things they would not tell a facilitator.

Facilitation note: Brief the interviewers on the checklist, the open-question principle (What? Why? How?), and the importance of silence — leaving space after an answer before asking the next question. The silence is where the real answer often lives.

Learning Journal / Field Notes

Origin: Action Research / ethnographic practice Phase: Gather (ongoing throughout) Format: Individual, ongoing. Can be written, drawn, voice-recorded. Time: 5–10 minutes at end of each session minimum

Description: Each participant (students and facilitators) keeps an ongoing record of what they notice, what surprises them, what they don’t understand yet, and what they want to return to. This is not a formal document — it is a thinking tool.

In LFTI: Every block node can have a learning journal entry associated with it. The journal is the raw Gather data that hasn’t yet been through Collate.

Timeline

Origin: PLA/oral history tradition Phase: Gather — Past movement Format: Group or individual. Physical line on floor or drawn on paper. Time: 30–45 minutes

Description: Map significant events on a timeline. Can be personal (your own life), institutional (this school’s history), or community (what has happened in this place). Events are placed in sequence and can be annotated with feelings, significance, who was affected.

In LFTI: A personal timeline alongside a school’s institutional timeline can reveal the points at which individual students’ lives and institutional decisions intersected — and the places they didn’t, where the school was completely unaware of what was happening to its students.

Focus Group

Origin: Social research / PRA tradition Phase: Gather Format: Groups of 6–12, ideally homogeneous (same year group, same gender, same experience). Two facilitators. Time: 60–90 minutes

Description: Facilitated discussion around a set of open questions. The group dynamic generates responses that individual interviews don’t — agreement, contradiction, negotiation, surprise. The interactions between participants are as informative as the content of what they say.

Disaggregation note: Mixed groups often produce dominant-voice responses. Consider single-gender groups, or groups separated by year group, confidence level, or experience. The students who never speak in mixed groups will speak in homogeneous ones.

COLLATE PHASE TOOLS

Collaborative Prioritisation (tool category)

The following tools all serve the same purpose: helping a group find shared priorities without imposing an external ranking. Each has different dynamics. Choose based on the group, the context, and what kind of social process is appropriate.

The underlying principle: Prioritisation is a social act, not a calculation. The goal is not to find the “correct” answer but to make the group’s collective judgment visible to itself.

Stones in Circles (Resource Allocation / Proportional Weighting)

Origin: PRA field practice / Kamoto community methodology Phase: Collate Format: Facilitator-run, single shared display. Group sizes of 8–30. Time: 20–40 minutes

Description: The facilitator draws or places circles on a shared surface (ground, floor, whiteboard, paper). Each circle represents an option or priority identified during Gather. Each participant is given a fixed number of tokens (stones, coins, dots, votes — the physical material matters: stones are visible, weighty, and cannot be taken back easily). Participants distribute their tokens across the circles according to their priorities. They may put all tokens in one circle or spread them. The distribution is visible to the whole group as it develops.

The social dynamic is the methodology: Seeing others place their tokens is generative. It prompts reflection, reconsideration, and sometimes courage — to put your tokens somewhere unexpected, or to hold back from the obvious choice. This is not a bias to be eliminated. It is the collective sense-making process.

The visibility question: On shared devices vs. a shared physical display, the dynamic changes significantly. A physical display (stones on the ground, visible to everyone in the circle) preserves the social dimension. Individual devices (digital voting) produces cleaner data but a different social experience. The physical version is primary; digital is a secondary option.

Facilitator-run single screen: The facilitator distributes tokens on screen based on participants’ verbal or hand-raised instructions. Everyone watches. This is the recommended digital implementation — it preserves the social visibility without requiring individual devices or network connectivity.

Output: A weighted distribution. Not a winner — a picture of where the group’s attention and energy sits. Multiple circles with roughly equal weight is as informative as one dominant circle.

Matrix Ranking

Origin: PRA/PLA tradition (AFCAP) Phase: Collate Format: Group. Drawn on ground with stick, or on paper/whiteboard. Time: 30–45 minutes

Description: A grid with options across the top and criteria down the side. Each cell is filled with tally marks (or stones, or dots) indicating how well this option performs against this criterion. The matrix is built by the group together, not filled in by the facilitator.

In LFTI: Useful for evaluating possible responses, interventions, or changes identified during Gather. “Which of these things would make school better?” × “Cost / Feasibility / Student control / Impact.”

The tally mark version is intentionally non-numeric: Seeing IIIII vs II is different from seeing 5 vs 2. The visual weight of marks carries more than the number.

Pairwise Ranking

Origin: PRA/PLA tradition (AFCAP) Phase: Collate Format: Group or small group. Paper or ground. Time: 20–30 minutes for up to 6 items

Description: Given a list of items, compare each pair: which of these two matters more? After all pairs are compared, count the wins. The ranking emerges from the comparisons, not from asking people to rank directly.

Why it works better than direct ranking: Direct ranking (“put these in order”) produces a list that reflects what people think they should say. Pairwise comparison (“just these two — which one?”) surfaces genuine preferences by reducing the cognitive load and the social performance.

Limitation: Works for small lists (up to 6–8 items). Becomes unwieldy with more.

Body Voting / Human Spectrum

Origin: PLA / community organising / Theatre for Development Phase: Collate Format: Whole group, standing. Requires floor space. Time: 10–20 minutes

Description: A line is established between two poles (Agree / Disagree, This / That, Important / Not Important). A statement or image is presented. Participants position themselves on the line according to their view. No discussion during positioning. After everyone has placed themselves, the facilitator asks people at different points on the line to explain their position.

Why it is powerful: You can see the distribution of the whole group at once. You cannot hide — you must take a position. Students who would not raise their hand will walk to a point on a line. The physical commitment is lower but the visibility is higher.

In LFTI: Particularly useful for surfacing disagreement within a group — and for making visible that disagreement is not a problem but a feature. “Look — we are not all in the same place on this. That is interesting. Why?”

Affinity Grouping / Card Sorting

Origin: Design thinking / PLA tradition Phase: Collate Format: Group. Physical cards or sticky notes on a wall or floor. Time: 30–45 minutes

Description: All Gather artefacts (or summaries of them) are written on individual cards. The group arranges the cards into clusters based on similarity, without predefined categories. Categories emerge from the clustering. The group then names each cluster.

The naming act is critical: The name the group chooses for a cluster is their analysis of what those things have in common. It often surprises people. It often produces a word or phrase that becomes the organising concept for the Present.

Digital version: Cards as nodes in the system, grouped by the group’s decision into synthesis nodes. The physical version is preferable for the initial grouping — the act of moving cards by hand is part of the thinking.

Venn Diagram (Actual / Ideal pair)

Origin: PRA/PLA tradition (AFCAP, Chambers) Phase: Collate Format: Group drawing. On ground, floor, paper. Time: 30–45 minutes per diagram; 60–90 minutes for the pair

Description: Draw circles representing institutions, people, or forces that affect the group’s experience. Circle size represents significance/importance. Distance between circles represents interaction — circles that touch or overlap have strong interaction; circles that are far apart have little.

The actual/ideal pair: Draw the current situation first (actual). Then draw what you wish it looked like (ideal). The gap between the two is the analysis. The circles that have moved, changed size, or changed relationship between the two versions are where the group’s energy lives.

In LFTI Situation movement: “Draw the people and institutions that affect your experience of school.” Then: “Draw what you wish it looked like.” The student body, the teacher, the headteacher, the government, the family, the curriculum — where are they now? Where should they be?

Causal Flow Diagram

Origin: PRA/PLA tradition (AFCAP) Phase: Collate Format: Group. On ground or paper with sticks/markers. Time: 45–60 minutes

Description: Starting from a central problem identified during Gather, the group maps causes (flowing in) and effects (flowing out). Causes of causes. Effects of effects. The diagram grows outward. Eventually the group can see the structure of the problem — which causes are roots (far upstream) and which are symptoms (close to the centre).

The blue/green coding (from AFCAP): Blue nodes are causes. Green nodes are effects. This visual distinction makes the structure of the problem legible.

In LFTI: “What causes school to feel the way it does?” The diagram will show root causes (policy, funding, teacher training, cultural expectations) and proximate causes (class size, timetabling, assessment pressure) and effects (disengagement, anxiety, boredom, exclusion). The group can then ask: where in this diagram do we have leverage?

Spectrum Line (Two Poles)

Origin: PLA / facilitation practice Phase: Collate Format: Physical line or drawn continuum. Individual positioning. Time: 15–25 minutes

Description: Place two opposing concepts at either end of a line. Participants place a Gather finding, idea, or statement on the spectrum between the poles. The placement is their analysis.

Example poles for LFTI:

Within our control ←→ Outside our control
This happened to us ←→ We chose this
School caused this ←→ We brought this with us
This is about Past ←→ This is about Futures

The spectrum is not a ranking — it is a relationship. Things placed near the centre are genuinely ambiguous. That ambiguity is valuable.

Most Significant Change

Origin: Rick Davies / participatory monitoring and evaluation tradition Phase: Collate (end of cycle) / Present Format: Individual reflection first, then group. Time: 30–45 minutes

Description: At the end of a cycle, each participant identifies the most significant change they observed or experienced, and why they think it is the most significant. These stories are shared in a group. The group then discusses which change story they find most significant, and why.

The “why” is more important than the “what.” The criteria by which people judge significance tells you more than the changes themselves.

In LFTI: Run at the end of each movement’s Present phase. “What is the most significant change in how you understand your own experience of school, since we started?” The meta-reflection on the methodology itself is part of the data.

Synthesis Node (Placeholder)

Origin: To be developed Phase: Collate Format: TBD Description: A shared surface on which a group produces a collective representation that did not exist in any single Gather artefact. The synthesis is not a summary — it is a new thing that only the group could make. It may be a composite map, a collective body map, a jointly produced narrative, a scored diagram.

This node is a placeholder. The synthesis canvas is the most technically complex piece of the Collate phase and is deferred to a later development cycle. What exists now: a synthesis node can hold images, text, and relations to the Gather artefacts it draws from. The collaborative creation tool does not exist yet.

The synthesis output is itself a node with feeds relations to Present and to Whole → Gather.

Triangulation Check

Origin: PRA/PLA tradition Phase: Collate (final step before Present) Format: Facilitator-led reflection with the group. Time: 20–30 minutes

Description: Before moving to Present, ask: what did multiple methods tell us? Where did the body maps, transect walks, story circles, and interviews agree? Where did they contradict? The contradictions are not problems — they are the most interesting findings.

Questions:

Which findings appeared in more than one method?
Which findings appeared in only one method — and why might that be?
Whose voice is missing from what we’ve gathered?
What would we need to gather to be more confident in what we’re seeing?

PRESENT PHASE TOOLS

Live Performance

Origin: Theatre for Development / Kamoto Community Arts / Augusto Boal Phase: Present Format: Performed to an audience. Audience may be passive (theatre) or active (forum theatre).

Variants:

Forum Theatre (Boal): A scene is performed showing a problem. At a key moment, the action is frozen. The facilitator (Joker) asks the audience: what should happen next? Audience members can replace an actor and try a different response. The scene runs again, differently. There is no correct answer — only the exploration of possibilities. The audience are spect-actors, not spectators.

Image Theatre (Boal): Participants make frozen images with their bodies — a sculpture showing “how it is” and then a second showing “how it could be.” No words. The images are read and discussed. A non-verbal version of the Venn actual/ideal pair, but embodied. Works across language barriers.

Verbatim Theatre: The performers speak the exact words gathered during Gather (from interviews, story circles, peer interviews). Nothing invented. The power comes from recognising: these are real words, said by real people, about real experience.

Music / song: An original song, or an existing song with new words, performing the findings of Gather. Kamoto’s tradition includes music as a primary vehicle for community reflection.

Dance / movement piece: Choreographed or improvised movement expressing the findings. The body that was mapped in Gather becomes the instrument of presentation.

Transect Walk as Presentation

Origin: PRA/PLA tradition (Episcopal Relief & Development) Phase: Present Format: Participants lead an audience along the route they walked during Gather.

Description: The participants become guides. They lead community members, other cohorts, or decision-makers along the transect route, stopping at each zone to narrate what they found, what they observed, what they felt. The walk is the report. The audience experiences the space in the same sequence the students experienced it.

Cross-cohort version: A UK cohort presents their school transect to a Zambian cohort over video. Each stop on the walk is a node that can be viewed and responded to asynchronously. The comparison between two school transects is a cross-cohort interchange in itself.

Exhibition

Origin: Participatory Photography / visual arts practice Phase: Present Format: Displayed artefacts in a shared space, physical or digital.

Physical exhibition: Body maps, transect diagrams, photographs, drawings displayed on walls or ground. The gallery walk (audience in silence first, then response) is the viewing methodology.

Digital exhibition: Images and text displayed as nodes in the spine, with the _visibility: portal flag marking them for eventual public display.

Audience response: Leave response cards, sticky notes, or a response book. The audience’s response to the exhibition is itself Gather material for the next cycle.

Short Video

Origin: Contemporary student communication / digital media Phase: Present Format: Individual or small group produced. Phone camera sufficient.

TikTok / Reels format (60–90 seconds): The constraint is generative. You cannot explain everything. You must choose. What is the one thing this student wants to say about their experience of school? The constraint forces the kind of clarity that longer forms allow you to avoid.

Documentary format (5–15 minutes): More space for complexity. Interview-based or observational. Students as directors, camera operators, and subjects.

The channel as ongoing Present: A project channel (YouTube, Instagram, TikTok, or private equivalent) that accumulates content over the life of the project is not a single artefact — it is a living Present. Each contribution is a block node. The channel is a session node with an open window.

Cross-cohort exchange: A UK student’s 60-second video about their school morning alongside a Zambia student’s 60-second video about their school morning. Same form, same constraint, genuinely comparable.

Podcast / Audio

Origin: Contemporary media / oral history tradition Phase: Present Format: Recorded conversation, interview, or narration. Phone mic sufficient.

Interview format: One student interviews another using the semi-structured checklist approach. The audio is the artefact.

Story format: A student narrates their own story directly to the microphone. No interviewer. The intimacy of audio — you are in someone’s ear — produces a different kind of listening than reading or watching.

Cross-cohort exchange: Audio messages exchanged between cohorts before video exchange is possible. Lower bandwidth requirement. Can be asynchronous.

Zine / Photo Essay

Origin: DIY publishing / participatory photography / youth arts Phase: Present Format: Printed or digital. Individual or collective.

Description: A short, self-published document combining image and text. No professional production required. A phone photograph with a handwritten caption is sufficient. The zine form has a long tradition of giving voice to those without access to mainstream publishing.

Collective zine: Each student contributes one page. The collection is the publication. Print and distribute within the school. Send copies to partner schools.

Story of Self

Origin: Marshall Ganz / community organising tradition Phase: Present (but also a Gather tool for building narrative) Format: Individual narrative, structured. 3–5 minutes to tell.

Three elements:

Story of Self — why I was called to this. A moment that shaped who I am and what I care about.
Story of Us — what we share. What brought this group together. What we hold in common.
Story of Now — the challenge we face. Why this moment. What is at stake. What we are called to do.

In LFTI Present: A student telling the story of why this project mattered to them, using this structure, to another cohort or to a wider audience. Personal but not private. Specific but universal.

Pre-perceptions Delta (Evaluation Reveal)

Origin: Green Living Movement / LFTI methodology Phase: Present (Whole cycle — final) Format: Individual reflection + group sharing.

Description: Students retrieve their original pre-perceptions instrument. They complete a second version alongside the first. Then they share: what changed? What didn’t? What surprised you about what stayed the same?

This is the primary evaluation measure of the whole project. Not a test of knowledge acquired but a record of perception changed — or not changed, which is equally interesting.

The unchanged perception is as valuable as the changed one. If a Bristol student’s assumption about Zambian students is exactly the same after six months of exchange as before, that is the most important finding of all.

CROSS-CUTTING TOOLS

(Tools that appear in multiple phases)

Hot Seating

Origin: Drama in Education / Theatre for Development Phase: Gather (generating stories) / Present (performing them) Format: One participant in role, group asks questions.

Description: A participant takes on a role — themselves at a different age, a character from their story, a figure of authority in their school. The group asks questions. The person in role answers as that character. The role distance is protective — you are not speaking as yourself, so you can say things that would be harder to say directly.

In LFTI: A student in role as their year-3 self, being asked about their first experience of school. Or a student in role as their headteacher, being asked why the rules are what they are. The role-play surfaces knowledge that direct questions don’t reach.

Learning Journal (ongoing)

Phase: All phases See Gather phase entry above.

PROVENANCE NOTES

Several tools in this library have specific origins that must be honoured:

Kamoto Community Arts / George Daka, Phillip Kaluba, Mary Manzole: The Body Map facilitation protocol, the Participatory Performance Practice (PPP) framework, and the community arts methodology that underlies LFTI’s approach to the body as instrument. These tools originate in Zambia. When used by LFTI, they are used with permission and in partnership — not borrowed or adapted without acknowledgement.

Green Living Movement / Emmanuel Mutambashiku: The Pre-perceptions instrument. Used throughout LFTI as the primary evaluation mechanism.

Augusto Boal / Theatre of the Oppressed: Forum theatre, image theatre, the spect-actor concept. A formal body of work with its own literature, training tradition, and ethical framework. Facilitators using these tools should have specific training.

Robert Chambers / PRA tradition: Handing over the stick, triangulation, sitting down, optimal ignorance. These principles are widely documented but originate in a specific methodological tradition that deserves citation.

Wang & Burris / PhotoVoice: The SHOWED methodology and the participatory photography framework.

Marshall Ganz / Harvard Kennedy School: Story of Self / Story of Us / Story of Now. Developed in the context of community organising; applies directly to LFTI’s Present phase.

SEEDING INSTRUCTIONS FOR CLAUDE CODE

When seeding the reference instance from this document:

Each ### heading under a phase becomes a tool node with type: "tool" and meta._level: "reference".
Each phase heading (GATHER, COLLATE, PRESENT) becomes a cycle phase node with meta.phase set accordingly.
The PRINCIPLES & ETHOS section becomes a methodology node above the phase nodes, with contains relations to each principle node.
Variants listed under a tool become block nodes under the tool node, with sequence relations between them where order matters.
Facilitation steps go in the node body, not as child nodes — they are content, not structure.
Provenance notes become involves relations pointing to the relevant institution nodes (Kamoto, GLM, etc.) already seeded in the main LFTI tree.
Placeholder nodes (Synthesis) get meta._placeholder: true and a body noting what is deferred and why.
Cross-cohort versions of tools get meta.context: ["cross-cohort"] and a responds_to relation placeholder.
All reference instance nodes get meta._visibility: "partners" — visible to collaborating institutions, not public.
The Body Map node gets a specific note: meta._facilitation_owner: "Kamoto/Mary Manzole" and meta._status: "protocol_pending".

The Spine — generic architecture, and how to reseed it

2026-08-12T00:00:00.000Z

Written 2026-08-12, from the state of the codebase at that date.

LFTI is not really an app about participatory education. It is a small general-purpose node graph editor — the spine — with a participatory education seed planted in it. Everything domain-specific grew from that seed. The point of this note is to name which parts are the spine and which are the seed, so the same essence can be replanted in another domain without re-deriving it.

1. What the spine actually is

The generic layer is small. Roughly 460 lines of server and a few thousand of client:

Piece	File	What it gives you
Node CRUD	`api/nodes.js`	one table, one shape, recursive delete
Storage + visibility	`db/database.js`	SQLite, relation index, role filter
Auth	`api/auth.js`, `middleware/auth.js`	sessions, roles
Attachments	`api/images.js`	files on any node
Views	`lfti.js`	tree / position / graph, capture, relations

Everything else — projects, cycles, phases, tools, classes, groups — is seed.

The one data structure

Every single thing in the system is a row in nodes:

id · parent_id · title · body · type · tags · created_at · updated_at · meta · relations

That is the whole schema for content. There is no projects table, no classes table, no tools table. type is a free string, meta is free-form JSON, and relations is a JSON array of { id, type, target, label }.

This is the central bet, and it is the thing worth copying. A new domain concept costs you a new type string and some meta keys — no migration, no new endpoint, no schema change. The cost is paid later, in that nothing is enforced: every invariant lives in code and can drift. Both halves of that trade showed up in LFTI and are documented in §4.

Two axes, deliberately

parent_id — the containment tree. Exactly one parent. This is what the left-hand tree renders and what recursive delete follows.
relations[] — a directed graph over the same nodes, many-to-many, typed. In LFTI: contains, involves, references, sequence, feeds, hosts.

Almost every interesting question (“what feeds this?”, “what does this reference?”) is a graph question, while navigation and lifecycle are tree questions. Keeping both, and being clear which is which, is most of the architecture. relations_index is just a denormalised copy of relations[] for querying in the other direction.

Levels — reference vs instance

One meta key does an enormous amount of work: _level.

_level: 'reference' — canonical, authored-once methodology. The 33 tool definitions. Read-mostly, visible to everyone, never owned by a school.
_level: 'instance' — a live running thing. A project, a class doing a tool on a Tuesday, a contribution.

An instance points at its reference with a references relation and copies what it needs to vary. That single distinction is what lets one body of methodology serve many cohorts without either drifting into the other. If you reseed, keep this. It is the most transferable idea in the codebase.

Visibility as a pure function

filterNodesByVisibility(nodes, user) takes the whole node set and a user and returns what they may see, by these rules in order:

superadmin sees everything
anyone authenticated sees _level: 'reference' or _visibility: 'public'
_visibility: 'portal' is visible to any authenticated user
a node whose meta.institution_id matches the user’s
anything under the user’s institution by walking parent_id upward

The client then fetches the whole visible set in one call and renders from memory. That is why the app feels instant and why the tree, graph and position views are cheap — they are all just projections of one in-memory map.

The limit of that design: the client holds everything it is allowed to see, so any UI-side role switching is cosmetic. LFTI’s “view as” switcher is explicitly a preview, not a permission test, for exactly this reason.

2. What the seed is

The domain layer, in dependency order, is about 1,700 lines of server:

institutions (126)  →  projects (451)  →  tool-instances (349)
                                       →  class-instances (648)
                          token-login (80)   filter-options (69)

And a vocabulary of types layered on the generic node:

institution → container → project → cycle → session → tool_instance
                                          → class_instance → group_instance
                                                           → artefact

Plus tool (reference), class, person, block, exchange.

Nothing in the spine knows any of these words. They are conventions the domain routes agree on. You could delete every file in api/ except nodes.js, auth.js and images.js and still have a working generic outliner.

How the seed gets planted

seedLFTI() is a plain function that builds a node map, extracted from source at boot and run in a sandbox when the database is empty. The methodology comes in as data, not as schema. That is why the tools could be re-tagged wholesale (produces / consumes) via one idempotent migration script without touching a single table definition.

3. Roadmap for a new seed

If you wanted to plant a different domain in the same spine, this is the order that would have saved LFTI the most rework. Roughly the order it happened, with the mistakes taken out.

Phase 0 — decide the vocabulary before writing code. Write the type list and the relation list as a flat document. For each type: is it reference or instance? What is its parent? What does it point at? An afternoon here is worth weeks later. LFTI’s single most expensive defect — two rival “class” entities, one under the project and one under the school — is a Phase 0 omission, and it was still blocking work months later.

Phase 1 — spine only. Node CRUD, tree view, capture, relations, delete. No domain words at all. You should be able to build an arbitrary outline.

Phase 2 — auth and visibility. Roles, sessions, and the visibility function. Do this before the domain, because visibility rules shape what the domain is allowed to assume. Write the role ladder down.

Phase 3 — the reference layer. Author the canonical content as a seed function: your equivalent of the 33 tools. Mark it _level: 'reference' and _visibility: 'public'. Resist adding instance concepts here.

Phase 4 — one instance chain, end to end, for one user. Pick the single most important path — for LFTI: institution → project → phase → tool instance → group → contribution — and build it all the way through for one role. Do not build breadth. A chain that works end to end tells you more about the model than five half-built layers.

Phase 5 — the second actor. Add the role that consumes what the first produces (teacher watching students). This is where the model gets tested, because it forces the question of what rolls up and what stays local.

Phase 6 — the working surface. The page the end user actually touches, with its own affordances. LFTI got here late: group pages existed for months as bare contribution lists before becoming worksheets, so nothing could actually be run in a classroom.

Phase 7 — feedback and learning. Only once real usage exists. Anything that learns from history needs history, and history needs the working surface from Phase 6 to have been used in anger.

Three ordering lessons, dearly bought

Write side before read side. LFTI rendered “in progress · step 3” and stuck-timer warnings in seven places for months while nothing ever wrote a step trace. The display was finished and the data never arrived. Build the writer first, even if it is ugly, then the readers have something true to render.
Gate on the thing the user actually produces. The step-completion gate was first built against a separate step-tagged contribution, which meant nothing the user naturally did could unlock it. Moving the gate to the note in the worksheet — the thing they were already typing — made it work.
A feature with no entry point does not exist. The responds_to relation, the whole cross-phase feed-forward mechanism, was fully built on both sides and had zero instances in the database because the button was somewhere nobody went.

4. Where the flat model bites

Worth knowing in advance, because all of these are consequences of the schema bet in §1 and every one of them cost real time here.

Nothing is enforced. meta.institution_id may be a slug ('uk') or a node id ('inst_uk_schools') depending on which code path wrote it. Every reader carries a fallback map. Pick one representation on day one.
Deletion cascades the tree, not the graph. Deleting a node removes its descendants and its outbound relations, but inbound relations from elsewhere survive and dangle. Sweep them or accept the debt knowingly.
Single parent_id forces a choice the domain may not want. A class genuinely belongs to both a school and a tool run. LFTI resolves this with class_instance as a projection of a class into a tool — which works, but is the kind of thing to decide deliberately rather than discover.
Seeds drift from their loader. seedLFTI() moved from the HTML into lfti.js and the loader kept reading the HTML, so a fresh database silently seeded zero nodes for months behind a console.warn. If a code path only runs on first boot, it is untested by definition — test it explicitly.
Docs rot faster than code. KNOWN_ISSUES.md asserted that tool-to-tool relations already existed in the graph (there were none) and that students were read-only (they had not been for some time). Design notes describing intent age badly once they start describing state.

5. The transferable essence, in one paragraph

One node table with a free-form type and JSON meta; a containment tree and a typed graph over the same nodes; a hard split between authored reference content and live instances that reference it; visibility as a pure function of node plus user; and the whole visible graph shipped to the client so views are just projections. Plant a domain in that as seed data rather than as schema, build one chain end to end before building breadth, and always build the thing that writes before the thing that displays.

Mapping the opportunity — how it was built

2026-08-11T00:00:00.000Z

Method, reliability and findings behind the southern England screen

Technical companion note | August 2026

This note explains how the southern England screen was produced, how far each step can be trusted, and what the resulting numbers do and do not mean. It is written to be argued with: every judgement is named, every weakness stated, and every figure traceable to an open dataset.

1. The data

Everything used is open, and everything is vector or tabular - there is deliberately no terrain data and no satellite imagery, so the whole analysis runs on an ordinary laptop from about 130 MB of downloads. The study area is Somerset to Kent, the south coast to roughly the Thames: 365 by 140 kilometres.

Dataset	What it gives us	In our area	Source
EA Hydrology API	Daily mean river flow, 2015-2025	374 stations, 1.47M readings	Environment Agency
BGS 1:625k Hydrogeology	Which rock is where, and how productive	2,485 polygons	BGS / UKRI
WFD Groundwater Bodies	Regulatory units and their health status	123 bodies	Environment Agency
OS Open Rivers	The river network, and which way it flows	24,714 links	Ordnance Survey
BGS GeoIndex boreholes	Where holes were drilled, and how deep	248,516 records	BGS / UKRI
Source Protection Zones	Groundwater protected for public supply	1,789 zones	Environment Agency
SSSI / SAC / SPA / Ramsar	Protected wildlife sites	2,943 sites	Natural England
CaBA Chalk Streams	Designated chalk stream reaches	6,372 reaches	The Rivers Trust

2. Turning flow records into a ‘divertible volume’

This step produces the headline number, so it deserves the most scrutiny.

The idea. You cannot take water from a river whenever you like. An abstraction licence typically says: don’t start pumping until the river runs high, and never draw it below a floor. We applied that shape of rule to every gauge. The trigger is the flow the river exceeds 12.5% of the time - a high flow, below which pumps stay off. The hands-off level is the flow it exceeds 19% of the time, and the river is never drawn below it. On a day above the trigger, the divertible volume is whatever sits between the two, multiplied by the seconds in a day.

Both thresholds come from each station’s own record, so a small Sussex stream is judged against its own behaviour rather than a regional average. Totals run over water years (October to September) so a winter is never split across two annual figures, and a year counts only if at least 95% complete.

How reliable is it?

Three checks, done rather than assumed. The Thames at Kingston was recalculated from the raw data by separate code sharing nothing with the main pipeline: 431.48 Mm3/yr both ways. The arithmetic reproduces its own definition - days when diversion is allowed should be exactly 12.5% of the record, and across 370 stations the measured figure is 12.43%. And the ‘winter surplus’ claim was tested rather than asserted: the rule contains no season, so nothing forced the answer, yet 92% of divertible volume falls between October and March, and no candidate falls below 88%.

A real problem we found, and fixed

The Environment Agency publishes three daily flow series per station - mean, minimum and maximum - and the field identifying which is which is missing from the API’s search results. Our first run silently pulled the daily minimum for 123 stations and the maximum for 134; only 117 of 374 were correct. The statistic turned out to be recoverable from the series identifier, so it was fixed and everything re-fetched. Anyone reusing that API is exposed to the same trap, and it would not announce itself.

How this step could be improved

A drought sensitivity would help most: a ten-year mean hides how far the resource falls in a dry year, which is exactly when stored water is wanted. The two thresholds are inherited from the Somerset work and undefended in this region - they deserve testing. And many stations reach back to the 1960s, which would let variability be separated from trend.

3. What was actually analysed

Every gauge follows the same sequence. Nothing is weighted and nothing is combined into a single score:

374 flow gauges → 370 with a usable daily-mean record → 83 clearing 20 Mm3/yr → 73 also within 15 km of a suitable aquifer → collapse to 28 independent river systems → ranked by aquifer tier first, volume second.

The aquifer test has two tiers, printed in the output rather than hidden inside a score. Tier 1 is intergranular rock - water moves through the pore spaces between grains, like a sponge, so storage behaves predictably. Here that means Lower Greensand and Triassic sandstone, 1,500 km2 in the study area. Tier 2 is the Chalk, where water moves through cracks: less predictable, but this is the aquifer Britain has actually stored water in, and the North London scheme uses confined Chalk. Tier 1 outranks tier 2 at equal volume.

One exclusion by judgement. The Jurassic oolitic limestones pass the tier-2 test on the official classification and were excluded anyway, because our own Somerset boreholes show them behaving differently: the water table at Mells rises and falls 2.37 m a year, against 6.5 to 13.4 m in three Chalk boreholes. They are still drawn on the map, hatched and labelled as excluded, so the judgement can be challenged rather than disappearing into a filter.

Nesting - the most important step. Flow at one gauge already includes everything upstream of it. Kingston measures the same water as Reading and Windsor, and also the Mole and the Wey, which join the Thames under their own names - so grouping by river name would miss every tributary. Instead the Ordnance Survey river network itself was traced: each link knows its start point, end point and flow direction, which establishes exactly which gauge lies downstream of which. The effect is large. Adding all 73 candidates gives 5,446 Mm3/yr; the 28 genuine systems total 1,943. Nearly two thirds of the naive figure is the same water counted repeatedly.

Three things are reported but never scored: groundwater body status, all constraint layers, and borehole evidence. They change how a row reads, not where it sits. Scoring them would mean asserting regulatory and geological judgements this screen has no basis to make.

4. The map, and how to read it

Figure 1. The screen. Full-resolution version supplied separately - the detail rewards zooming.

Blue and pink areas are the two aquifer tiers - blue intergranular, pink Chalk. Diagonal hatching is the excluded oolitic limestone. Dotted shading marks groundwater bodies already in poor health.
Stars are candidate river systems. Colour is the tier; area is proportional to divertible volume, so twice the area means twice the water. Only the largest are labelled, to keep the map legible.
Small open circles are candidates upstream of a star and already counted inside it. Grey dots are the other 297 gauges, which did not qualify.
A black ring means that candidate stands inside a Source Protection Zone or a designated wildlife site.
Dark blue lines are designated chalk streams; pale blue is the ordinary river network.

What the map does not say. Nothing about how much water an aquifer could hold, whether it is covered and able to retain water, or whether anyone would be permitted to do any of this. Blank areas are not ‘no opportunity’ - they are places with no gauge, or a gauge that missed a threshold.

5. Findings, and what the numbers mean

Top of each tier; the full 28-row table is in the accompanying technical report.

tier	system	river	Mm3/yr	subsumes	WFD status	constraint
1	Trews Weir	Exe	194.8	4	Good	none of the five
1	Allington	Medway	141.5	9	Poor	SPZ 0.5 km
1	Bradford on Avon	Bristol Avon	112.2	3	Poor	SSSI 0.5 km
1	Pallingham	Arun	92.2	2	outside	INSIDE SSSI
1	Crandon Bridge	King’s Sedgemoor Drain	81.3	0	Good	none of the five
2	Kingston	Thames	431.5	16	outside	chalk stream 39 m
2	Throop	Dorset Stour	115.5	2	Good	chalk stream 22 m
2	East Mills Combined	Hampshire Avon	92.6	3	Good	INSIDE SSSI + SAC
2	Low Hall	Lee	41.6	0	outside	INSIDE SPZ1
2	Welford	Lambourn	40.6	0	Poor	INSIDE SPZ3, SSSI + SAC

What ‘194.8 Mm3/yr’ actually means. Over 2015 to 2025, in an average year, 194.8 million cubic metres passed the gauge at Trews Weir above the hands-off flow, on days when the river was above the trigger. It measures how much water was theoretically available to a licence-shaped rule at that point on that river. It is not an amount anyone could take, store or use.

The traps, spelt out

1Never add two rows together. Each row already contains everything upstream of it. The 28 rows can be compared, but not summed with their own tributary gauges.

2Divertible is not available. No pump, pipeline, treatment plant, borehole or aquifer acceptance rate is considered anywhere in this screen. Whether the ground could swallow water at that rate is untested here - and in most real schemes it is the binding constraint.

3’Highly productive aquifer’ says nothing about storage volume. It describes how easily water moves through rock - and easy movement is as much a reason water will leave a store as a reason it will enter one. What decides whether a winter’s water is still there in August is confinement: a low-permeability cap above it. The 1:625k map cannot show that, because it maps rock at outcrop - where Chalk lies beneath London Clay, the map shows London Clay. Our Somerset measurements give unconfined Chalk a 41-day drainage half-life.

4Distances are straight lines. 15 km on a map is not 15 km of pipeline, and says nothing about the ground in between or who owns it.

5A gauge is a measuring point, not a proposed intake. It is where somebody chose to put a flow recorder, sometimes decades ago.

6Borehole counts are about evidence, not geology. The index carries no rock descriptions, thickness or yield. 808 boreholes near Riverside Park with not one reaching 50 m tells you a lot of shallow construction happened there and nobody drilled for water.

7An empty constraint column means ‘none of these five layers’, not ‘unconstrained’. Licensing, existing users, planning, land ownership and flood risk are all absent.

8’Inside’ is tested at the gauge point. A scheme is bigger than a gauge; four candidates sit within 10 metres of a boundary without counting as inside it.

6. Conclusions

1The resource is real, and concentrated. 28 independent systems clear 20 Mm3/yr, totalling 1,943 Mm3/yr. Kingston alone is 22% of that - one river system is nearly a quarter of the regional opportunity.

2Physical opportunity and regulatory difficulty are correlated, not independent. Three candidates stand inside a Source Protection Zone 1, the innermost protection ring around a public water supply. That is not bad luck: an SPZ1 exists because the aquifer beneath is productive and already used for supply. The same fact that makes a site score well is what put the zone there.

3The tier-2 list and the chalk stream map are nearly the same map. Eight candidates sit within 50 metres of a designated chalk stream. The most productive Chalk options are also the most politically exposed freshwater habitat in England.

4Six candidates carry none of the designations we can see, led by Trews Weir at 194.8 Mm3/yr - and three of the six are in Somerset.

5Nowhere is unexamined, but depth is scarce. Every candidate has boreholes nearby; four have none deeper than 50 m within 2 km. Pallingham is the thinnest - four boreholes, none deep - and is the fourth-largest tier-1 system.

7. What Somerset looks like in a regional frame

Somerset returns the largest cluster in the screen - and, more surprisingly, some of the least constrained sites in southern England. Of the six candidates region-wide sitting inside no designation at all, three are Somerset.

Somerset system	tier	Mm3/yr	rank in tier	constraint	boreholes <2km (deep)
Crandon Bridge	1	81.3	5 of 16	none of the five	56 (4)
Aller Drove Bridge	1	53.1	7 of 16	SPA at 10 m	17 (0)
Taunton Market	1	39.4	8 of 16	none of the five	84 (5)
Bason Bridge	1	38.5	9 of 16	none of the five	20 (2)
Pen Mill	2	33.9	6 of 12	SPZ at 0.6 km	101 (18)
Chiselborough	2	20.1	12 of 12	INSIDE SPZ 2c	7 (2)

Two specific flags for the local work. Chiselborough sits inside a Source Protection Zone (2c) and is part of the nine-gauge inflow set used in the Somerset model, where that constraint is currently not noted anywhere. And Aller Drove Bridge has 17 boreholes within 2 km with none deeper than 50 m - the thinnest evidence of any Somerset candidate. That is an investigation-cost warning, not a geological verdict.

An independent corroboration worth noting. The Somerset configuration records, in a hand-written comment, that Taunton Market duplicates the Bishops Hull reach and should not be summed with it. Tracing the Ordnance Survey river network from scratch, with no knowledge of those comments, reached the same conclusion. That points at a cheap and worthwhile next job: run the same tracer over all nine Somerset inflow gauges to verify independently that none contains another. The local model’s inflow total currently rests on hand-written notes; this would either confirm it or correct it, in about half a day.

8. Next steps

What is missing, and whether open data can supply it

What is missing	Can open data fix it?
Aquifer storage capacity - absent entirely	Partly. Outcrop area is known; specific yield and usable thickness are not published spatially. A bounded estimate with stated assumptions is possible; real numbers need the BGS Aquifer Properties Manual, which no public service supplies.
Confinement - only a crude proxy	No. The groundwater body dataset has no confinement attribute at all - checked across all 271 bodies in England. It needs borehole logs read by a person, and we now hold 248,516 scan links to read from.
Abstraction licences and existing users	Probably yes. The EA publishes licence data; not yet integrated. This is the biggest missing constraint.
Demand - who actually needs the water	Yes. Water company resource plans and Water Resource Zones are open. Water far from demand is not an opportunity.
How fast an aquifer will accept water	No. Requires field testing.

Analyses possible with data already held

Drought sensitivity: recompute divertible volume on the three driest water years per station, which answers ‘does this survive a dry decade’ without needing climate projections.
Threshold sweep: test whether the 20 Mm3/yr and 15 km cut-offs do real work or simply sit in a gap in the data.
Distance to demand: water far from anyone who needs it is not an opportunity. Water Resource Zones are open data, and this is a genuinely new axis that would reorder the table.
A first-order storage bound for tier 1: outcrop area multiplied by a plausible range of specific yield and usable thickness. Crude, but it would let the screen say whether the resource exceeds plausible storage - which is a stronger claim than it currently makes.
Borehole log triage: the deep holes on aquifer outcrop near each candidate already have scan links attached. The top twenty could be read by a person.

All code, method and intermediate figures are held in the project repository. Data fetchers are resumable and rate-limited; raw downloads are never modified after collection. Attribution: flow data © Environment Agency, OGL v3. Geology and borehole index © UKRI / BGS. Groundwater bodies, basin districts and Source Protection Zones © Environment Agency, OGL v3. Protected sites © Natural England, OGL v3. Chalk streams © The Rivers Trust. Contains OS data © Crown copyright and database right 2026.

This note was written in Word; the text above is a faithful conversion, and the original is the authoritative copy.

Download the original (.docx)
Read the screen it describes: Mapping the opportunity

Mapping the opportunity

2026-08-11T00:00:00.000Z

A first-pass screen for seasonal aquifer storage in southern England

Strategic working note v1 | draft for discussion | August 2026

1. The question

England’s geology is mapped in remarkable detail. Its rivers are gauged, its aquifers designated, its groundwater bodies classified. What does not exist is a map that puts those layers together and asks a single question: where does surplus winter river flow sit beside ground that could hold it until summer?

This note is a first attempt. It screens 370 river gauges across southern England for divertible winter surplus, tests each against the productive aquifers within reach, and records the regulatory state of the groundwater body beneath. It is built entirely from open data - Environment Agency flow records, BGS hydrogeology, Environment Agency groundwater bodies, Ordnance Survey rivers - and every figure in it can be re-derived.

What it is not. It is not a feasibility assessment and not a prediction of what would be licensed. Aquifer productivity maps say nothing about storage volume and nothing about confinement - and high productivity is as much a reason water will leave a store as a reason it will enter one. Nothing here is tested against abstraction pressure, existing licences, ecology, water quality, ground conditions or cost. It identifies where the physical ingredients coincide. That is a starting point for investigation, not a shortlist for construction.

2. Method

Divertible resource. For each gauge, from its own 2015-2025 daily mean flow record: a trigger at Q12.5 (the flow exceeded 12.5% of the time - a high flow) and a hands-off threshold at Q19, below which the river is never drawn. Divertible volume on a qualifying day is (flow - hands-off) x 86,400, annualised over water years so no winter is split across two totals. Each catchment is therefore measured against its own hydrology rather than a national threshold, and the rule is shaped like an abstraction licence condition rather than a wish.

Aquifer tiers. Two, ranked, with the reasoning stated rather than buried in a score:

tier	rule (BGS 1:625k, within 15 km)	km2 in box	units
1 intergranular	highly productive, significant intergranular flow (class 1A)	1,500	Lower Greensand; Triassic / Sherwood sandstone
2 fractured	highly productive, fracture-dominated - Chalk only (class 2A)	8,681	White Chalk; Grey Chalk
excluded	meets the tier-2 test, excluded by judgement	747	Great Oolite; Inferior Oolite

Tier 1 ranks above tier 2 because intergranular storage behaves predictably: water occupies pore space and stays where it is put. Tier 2 is retained despite fracture flow because it is proven in practice - the North London ASR scheme stores water in confined Chalk. The Jurassic oolitic limestones meet the tier-2 classification test and are excluded by judgement, on evidence: Environment Agency borehole records show the Inferior Oolite at Mells swinging 2.37 m a year against 6.5-13.4 m in three Chalk boreholes. Thin seasonal storage, not comparable. The exclusion is drawn on the map so it can be argued with.

The rule. A gauge is a candidate if divertible volume exceeds 20 Mm3/yr and a tier 1 or tier 2 aquifer lies within 15 km. 73 of 370 gauges qualify.

3. Two traps, stated before the results

Volumes are nested and must never be summed. Kingston on the Thames measures the same water as Reading, Windsor and Sutton Courtenay upstream of it - and also the Mole and the Wey, which join under their own names, so grouping by river name would miss them. Systems are therefore traced through the Ordnance Survey river network. The 73 candidates collapse to 28 river systems. Adding all 73 gives 5,446 Mm3/yr; the 28 systems total 1,943. Nearly two thirds of the naive figure is the same water counted again downstream. Each row below carries its own measured volume, which already integrates everything above it.

Volume is not opportunity. The Thames at Kingston is the largest divertible resource in the region by a factor of two - and it appears at number 17, because ranking is by tier first. A vast flow beside fractured chalk in the most heavily abstracted reach in England is not the same prospect as a moderate flow sitting on sandstone. Sorting the table by volume alone would say the opposite, and would be wrong.

4. Results

28 river systems pass: 16 on tier 1 intergranular aquifer, 12 on Chalk. Of these, 14 sit in a groundwater body at Good quantitative status, 4 at Poor, and 10 outside any body. By river basin district the resource is more evenly spread than expected - South West 13 systems and 830 Mm3/yr, Thames 6 and 701, South East 8 and 300, Severn 1 and 112.

Figure 1. The screen. Star area is proportional to river-system divertible volume; colour is aquifer tier. Hollow circles are candidates subsumed by a system downstream and must never be added to it. Full-size version available separately.

#	tier	system	river	Mm3/yr	subsumes	aquifer km	WFD quantitative status
1	1	Trews Weir	Exe	194.8	4	11.8	Good
2	1	Allington	Medway	141.5	9	0.0	Poor
3	1	Bradford on Avon	Bristol Avon	112.2	3	12.1	Poor
4	1	Pallingham	Arun	92.2	2	2.5	outside any body
5	1	Crandon Bridge	King’s Sedgemoor Drain	81.3	0	4.6	Good
6	1	Whitford	Axe	70.2	0	14.7	Good
7	1	Aller Drove Bridge	Sowy River	53.1	0	5.2	Good
8	1	Taunton Market	Tone	39.4	1	2.0	Good
9	1	Bason Bridge	Brue	38.5	0	9.3	outside any body
10	1	Sherman Bridge	Cuckmere	38.0	0	0.7	outside any body
11	1	Barcombe	Ouse	35.1	3	0.6	outside any body
12	1	Woodmill	Culm	34.8	0	4.8	Good
13	1	Sakeham	Adur	33.8	0	2.4	outside any body
14	1	Dotton	Otter	31.2	1	0.0	Poor
15	1	Hardham	Rother	27.7	0	0.0	Good
16	1	East Stoke Flume	Dorset Frome	25.1	0	6.3	Good
17	2	Kingston	Thames	431.5	16	8.2	outside any body
18	2	Throop	Dorset Stour	115.5	2	12.1	Good
19	2	East Mills Combined	Hampshire Avon	92.6	3	2.7	Good
20	2	Low Hall	Lee	41.6	0	9.4	outside any body
21	2	Welford	Lambourn	40.6	0	0.0	Poor
22	2	Pen Mill	Somerset Yeo	33.9	0	9.3	Good
23	2	Testwood	Test	28.0	1	9.8	Good
24	2	Stifford	Mar Dyke	23.7	0	0.7	Good
25	2	Plucks Gutter	Kent Stour	23.1	0	0.9	outside any body
26	2	Redbridge	Roding	22.5	0	7.9	outside any body
27	2	Riverside Park	Itchen	21.7	0	7.6	outside any body
28	2	Chiselborough	Parrett	20.1	0	7.2	Good

Shaded rows are the Somerset Levels cluster (section 5). ‘Aquifer km’ is the distance to the aquifer of the row’s own tier. ‘Subsumes’ counts upstream candidates whose water this row already contains.

5. The finding that was not expected

The Somerset Levels - the landscape that motivated this work because of its flooding, not its geology - return the largest single cluster in the region. Seven systems in the table lie in or immediately around the Levels: King’s Sedgemoor Drain at Crandon Bridge (81.3 Mm3/yr), the Axe at Whitford (70.2), the Sowy at Aller Drove Bridge (53.1), the Tone at Taunton Market (39.4), the Brue at Bason Bridge (38.5), the Somerset Yeo at Pen Mill (33.9) and the Parrett at Chiselborough (20.1). Together they represent 336 Mm3/yr of divertible winter surplus - more than any other locality in the screen, and drawn from a landscape whose water problem is conventionally described as an excess.

Five of the seven are tier 1, on Triassic sandstone with significant intergranular flow, at measured distances of 2.0 to 9.3 km - not the 42 km to the Dorset Chalk that earlier work in this programme had assumed was the nearest credible store. Four sit in the ‘Tone and North Somerset Streams’ groundwater body at Good quantitative status. This is a regional screen that knew nothing about the Somerset project, applying a uniform rule to 370 gauges, and it nominated the Levels independently.

The caution that must travel with it. The Triassic outcrops are small (242 km2 across the whole region), the screen measures distance to outcrop rather than the presence of a usable store, and the BGS summary for these rocks notes they become saline at depth beneath confining Mercia Mudstone - which is simultaneously the confinement that would make storage work and a water-quality limit on where it could. Nothing here establishes that a store exists. It establishes where to look, and that the answer may be much closer to hand than assumed.

6. What this screen cannot see

Confinement - the decisive property. Whether an aquifer holds a winter’s water or drains it in weeks is set by confinement, not by productivity class. Local measurement in this programme put unconfined Chalk recession at a 41-day half-life. The Water Framework Directive dataset carries no confinement attribute at all: across all 123 groundwater bodies in the study area, the relevant fields are uniformly ‘Not Applicable’. Distance to a mapped covering formation is reported as a proxy, but the 1:625k map shows bedrock at outcrop - where Chalk is confined beneath London Clay the map shows London Clay - so the proxy locates the edge of a confined margin and cannot demonstrate confinement at a point. Confinement must come from borehole logs.
Storage volume. No open dataset supplies it. The BGS aquifer-properties service was queried directly during this work: it is a site index recording where property data is held, with no transmissivity and no storativity values. Productivity class describes how readily water moves, not how much the rock will hold.
Licensing and abstraction pressure. The WFD quantitative status column is reported and deliberately not scored, because it cuts both ways: Poor status is where recharge is most wanted and new abstraction hardest to permit; Good status beside a protected chalk stream may be untouchable. Existing licences are not modelled.
Source protection zones. No SPZ dataset was available; the join is written and the column will populate when one is supplied.
Cost, terrain and conveyance. No pipeline routing, no pumping head, no capital cost. Two candidates with equal volume and equal distance may differ by an order of magnitude in cost once lift and route are considered.

7. What follows

Read the map as a shortlist for desk study, not for schemes. The right next step at any candidate is borehole logs: does a usable thickness of aquifer exist, is it confined, and what do its records say about yield?
Investigate the Somerset Triassic first. It is the largest cluster, the aquifer is intergranular and close, and the local modelling programme already has the flow records, terrain and demand context to test a scheme there quickly.
Add the missing layers. Source protection zones, abstraction licences and returns, and protected-site boundaries would each move candidates around, and all three are open data.
Treat the two tiers as different products. Local modelling in this programme suggests intergranular and fractured settings do different jobs: a confined store banks water for summer supply, while a fast-draining one returns it to the river as delayed baseflow. Both are useful; they are not interchangeable, and a candidate should be judged against the product it can actually deliver.

England has mapped its geology in remarkable detail. The next task is to map the strategic opportunity that geology presents - and then to test, at a handful of places, whether the opportunity is real.

Sources and attribution: flow data from the Environment Agency Hydrology API, daily mean 2015-2025 (OGL v3). Geology: BGS 1:625k Hydrogeology © UKRI. Groundwater bodies and river basin districts © Environment Agency, OGL v3. Contains OS data © Crown copyright and database right 2026. Method, full 28-system table with all attributes, and the appendix of subsumed gauges are in the accompanying technical report.

This note was written in Word; the text above is a faithful conversion, and the original is the authoritative copy.

Download the original (.docx)
Read the method note behind it: Mapping the opportunity — how it was built

The Jacobian Conjecture

2026-08-09T00:00:00.000Z

The main paper One Formula, Many Worlds A walk down to the determinant and back up to the broken Jacobian conjecture. Thirteen sections, twenty-two figures, and one ladder with no missing rungs.

The conjecture fell in 2026. This is the expedition that went down after it: what the determinant is actually measuring, why the schoolroom prohibition on dividing by zero is the same rule as Jacobi’s dependence alarm, and what the counterexample looks like when you stand close enough to see its shape.

The main paper is the spine. Everything below came out of writing it — a field appendix that examines the counterexample’s fiber as a single geometric object, a research note seeking expert assessment, and a one-page seed for where the ladder goes next.

The papers

Research noteBracket and Unique MechanismA research note from the Determinant Ladder expedition — observation and programme, seeking expert assessment.

Field appendixDown the NeedleA field appendix to One Formula, Many Worlds: the fiber of the counterexample as one geometric object · August 2026 · third edition

Paper II seedWhere The Ladder GoesA one-page seed for Paper II of the Determinant Ladder expedition.

Why this exists

2026-08-09T00:00:00.000Z

Most of what I do ends up as a folder. A model, some figures, a document that explains itself to nobody but me, and then the next thing starts. This site is the attempt to stop that.

The rule I am setting myself is that a piece goes up when it is legible, not when it is finished. A study with an open question at the end is more useful than one that quietly drops the question. So expect loose ends.

Things are filed under a project when one fits, and left unfiled when none does. The filing is deliberately cheap to change — work migrates between projects, projects merge, projects get abandoned, and none of that should cost anything or break a link.

If something here is wrong, I would like to know.

The Overspill

2026-08-01T00:00:00.000Z

Owns: The overspill mode — how the addends are laid, how the carry becomes visible as a consequence, and why the representation fades by number type without any adaptive logic. Supersedes: nothing. Addendum to Exchange.md, which owns the exchange act itself and rulings E1–E8. Status: Committed as built. CalculationRoom1D (Counting) ships on this spec and has been playtested. Cited by: calculation_room_1d.gd:12 · exchange_rod.gd:83, 110, 483 · The_Pass_Ledger:212. Note: §5 stage 1 is built; stages 2–4 are designed and unbuilt. §8 records what was in scope for the Counting build.

The Overspill

Fill-to-ten is grouping on instruction. Overspill is grouping because the container ran out.

1 · The act

7 + 6

The child places 7 in the ledger → seven units appear in the rod below, laid along it
The child places + and 6 (either order — but the operator must be placed)
The six are laid on after the seven → the frame overspills
The excess 3 pulsate — held, marked, watchable
They lift into a second row, on top of the first
Count full rows → 1 → tens column
Count the loose row → 3 → units column

Ledger and rod are synchronised. Placing a digit in the notation makes the quantity appear beneath it.

★ That synchronisation is A1’s bridge, running live: the rod holds the quantity, the ledger records it, and the child watches the two agree. The violation in place_value_house is a chart being asked to hold both. Here they are two objects moving together.

2 · Why the overspill is better

	The child sees
Fill-to-ten	“when you reach ten, group them” — a rule
Overspill	the frame is full and there is more — the excess has nowhere to be

The regrouping stops being an instruction and becomes a consequence of the material running out of room. That is a gift of the mechanic in the frozen sense: the honest physics does the teaching, and no dialogue is required.

The pulsate is the beat that makes it work — the excess is marked and held long enough for the child to predict what must happen before it happens.

3 · The array reading — and how it must NOT look

Two rows, first full, second holding three. Count the full rows; count the leftover.

★ Place value is the array with its width locked to the base.

Which is why 10 × 10 is the hundred square, and why one component gives rod, array and hundred by changing capacity and columns.

⚠ This is not the times-table array, and the visual must say so

	Cells are	Stay individuated?
Times-table array	countable units of the product — both dimensions meaningful	yes, throughout
Carry array	containers of the base — only the count of full rows matters	no — a full row stops being ten cells

A sealed row is one ten. If it still reads as ten cells, the material is asserting the opposite of what sealing means. §6 is how the visual carries that.

The rhyme with multiplication is a special case, not an identity — worth using, not over-claiming. A child doing column addition still meets array structure before Venus, which is transfer arriving in the material rather than the curriculum.

4 · It is the bar, not the number line

The apparatus below the ledger lays quantities end to end as lengths. That is the bar — cardinal, quantity-as-length (T3). The number line is positions — start at 7, hop 6, land on 13 (T4). A3 keeps them apart.

Visually near-identical; conceptually different; and showing both is standard, valuable practice — the bar answers how much, the line answers where you land.

So the rhyme is a feature, provided the corridor knows which is which:

The line gives the operation its meaning. The bar gives the carry its structure.

One consequence for the build: the two addends should be visually distinct in the rod — 7 in one shade, 6 in another. Then 13 reads two ways at once: as seven-and-six (the bond) and as one-ten-and-three (the place value). The double reading is the whole point, and it continues shrine_of_bonds’ work rather than repeating it.

5 · The fade — free, because the numbers grow

Stage	Representation	Works to	Arrives at
1	Lay along, overspill — the addends as extents	~20, max 30	Counting (max 9+9 = 18)
2	Pour and fill rows — no linear lay-out first	99	Whole (bigger sums)
3	Flats — a hundred is one object	beyond	hundreds
4	Ledger only — carry mark, no material	—	fluency

No adaptive logic and no flags. Counting’s bounds keep sums inside the line’s readable range; Whole’s bounds push past it; hundreds push past that. The material’s limits and the number-type bounds coincide — which is usually a sign the structure is right rather than imposed.

Stage 1 shows why the row breaks. Stage 2 assumes you know, and just does it.

6 · ★ The seal is a visual unification that keeps the parts

The two addends are different colours — 7 in one, 6 in another. On seal, the full row is shaded over: a darker treatment in the same hue family, so the two colours remain legible underneath.

Both readings survive at once:

seven-and-six — the bond, still visible through the shading
one-ten-and-three — the place value, asserted by the unification

Shading rather than recolouring is what keeps the first reading. Recolouring to a single ten-colour would erase the bond and repeat what shrine_of_bonds already taught rather than continuing it.

And the cell structure goes

On seal, the row’s internal dividers fade, and the row reads as one bar rather than ten boxes.

	Reads as	Because
Loose row	individuated cells	these are still separate countable units
Sealed row	one shaded bar, two colour regions	this is now one ten

★ Sealing turns ten discrete things into one continuous thing. That is precisely what promotion to the next denomination means — and it makes the sealed row into a bar, which is what a ten is at the next level up.

It also settles §3 without a rule: the times-table array keeps its cells because every cell is a countable unit of the product; the carry array loses them on seal because the row has stopped being ten of anything.

7 · Who does what

Act	Whose	Why
Placing digits and `+` in the ledger	child	the operator is a pre-emption; it cannot be omitted
Units appearing in the rod	automatic	notation and quantity are synchronised
Overspill and lift to row 2	automatic	it is physics, not a choice — the excess has nowhere else to be
Counting rows and leftover	child	the interpretation, which is where the mathematics is
Writing the carry and the units digit	child	notation is the child’s understanding, not the material’s behaviour

The rule: the material behaves; the notation is authored. The excess must lift — there is nowhere else for it — but nothing is written down until the child writes it.

8 · Tonight

Counting is single digit + single digit, so stage 1 only.

Needed: one frame, two addends laid distinctly, overspill, pulsate, lift to row 2, child counts and records. Not needed: pour-fill mode · flats · a tens frame that fills · regroup-down (single-digit subtraction never regroups — that arrives with Whole).

3 + 5 must produce eight loose in one row, no overspill, no carry — the no-carry case has to look plainly different from the carry case, or the carry teaches nothing.

Institution hierarchy, class instances and student allocation

2026-05-23T00:00:00.000Z

This is a substantial structural prompt. Read the full codebase before starting — particularly the existing node structure, auth system, project wizard, tool instance view, and group instance nodes. Understand what exists before changing anything.

Build and verify each phase before starting the next. Do not proceed to Phase B until Phase A is confirmed working.

OVERVIEW

This prompt does four things in sequence:

Phase A — Restructure institution hierarchy (Root → Country → Institution) and fix person node placement
Phase B — Class instance node type and class assignment
Phase C — Live student allocation with role-based group limits and teacher override
Phase D — Cross-class view at tool instance level and feedforward to Collate

PHASE A — Institution Hierarchy & Person Node Placement

Target structure

LFTI (root)
  ├── Reference Instance
  └── Country (UK)
        └── Institution (Bristol Academy)
              ├── Staff
              │     ├── Institution Admin
              │     ├── Teacher
              │     └── [assigned facilitators via involves relation]
              ├── Students
              │     └── Class (11S1)
              │           ├── Tom P (person node)
              │           └── Sarah K (person node)
              └── Projects
                    └── LFTI 2026

Database migration

The existing uk and zm nodes are country groupings, not institutions. Specific institution nodes need to sit under them.

Run a migration in db/database.js on startup (check if already run via a migrations table):

CREATE TABLE IF NOT EXISTS migrations (
  id TEXT PRIMARY KEY,
  run_at TEXT NOT NULL
);

Migration: inst_hierarchy_v1

Create Staff and Students container nodes under each existing institution node (uk, zm, inst_lfti). These are simple nodes with type: container.
Move existing person nodes: reparent them under the correct institution’s Staff or Students container. Match by institution_id in their meta.
Dev seed users: reparent to inst_lfti Staff container.
UK-institution person nodes (UK School Admin, Mr J Clark): reparent to uk Staff container for now (will move to specific school when school nodes are created).
Set parent_id correctly on all person nodes — never null for a person node.

Migration: project_container_v1

Under each institution node, create a Projects container node (type: container).
Reparent existing project nodes to sit under their institution’s Projects container.

New node types

Add to the recognised type list:

country — top-level geographic grouping (UK, NZ, Zambia)
container — organisational wrapper (Staff, Students, Projects, Classes) Containers have no content of their own — they exist to organise children. In the tree, containers render without a type badge, just their title. In the content section, containers show only their children grid, no body editor.

Creating a new institution (system admin only)

System admin creates a Country node first (if it doesn’t exist), then an Institution node under it. On Institution node creation, automatically generate:

Staff container node
Students container node
Projects container node

This should happen via a dedicated endpoint:

POST /api/institutions
  body: { name, country_id, admin_name, admin_email }
  Auth: superadmin only
  Creates: institution node + 3 container nodes + institution admin person node
           under Staff container
  Returns: { institution_id, admin_person_id }

The institution admin person node is created with meta.invite_status: "pending". Print their credentials to the server console (same pattern as dev seed).

Institution admin scoping

Institution admins can only create projects under their institution’s Projects container. Enforce this in POST /api/projects:

If role is institution_admin, verify that the target parent node is the Projects container of their institution. Reject with 403 if not.
Superadmin can create projects anywhere.

Project wizard changes

In the project wizard Step 1, the institution field is now read-only for institution_admin role — pre-filled with their institution. Only superadmin sees a dropdown to choose any institution.

Facilitator assignment

Facilitators are person nodes that may exist at country or root level (they work across multiple institutions). They are assigned to an institution or project via an involves relation — not moved in the tree.

In the Participants tab of the project dashboard, when adding a facilitator:

Search first among person nodes that have involves relations to this institution or its country ancestor
Also search all person nodes with role: facilitator system-wide
Selecting one adds an involves relation from the facilitator’s person node to the project node — does not change parent_id

Verify Phase A

As superadmin, create a new institution “Bristol Academy” under UK. Staff, Students, Projects containers auto-generate. Institution admin person node created under Staff. Credentials printed to console.
Log in as the new institution admin. Project wizard Step 1 shows Bristol Academy pre-filled, not editable. Creating a project places it under Bristol Academy → Projects container.
Attempting to create a project under UK Schools (wrong institution) as institution_admin returns 403.
All existing person nodes are now under institution Staff or Students containers, not at root level.

PHASE B — Class Instance Node & Class Assignment

Class instance node

A class instance is a thin wrapper that represents a specific class doing a specific tool instance. It sits between the tool instance and the group instances.

Tool Instance (Transect Walk)
  ├── Class Instance (11S1 — Transect Walk)   ← new node type
  │     ├── Group 1
  │     │     └── Contributions
  │     └── Group 2
  └── Class Instance (9J1 — Transect Walk)
        └── Groups...

Class instance node structure:

{
  "id": "ci_[timestamp]_[random]",
  "type": "class_instance",
  "title": "[Class name] — [Tool name]",
  "parent_id": "[tool_instance_id]",
  "relations": [
    { "type": "involves", "target": "[class_node_id]" },
    { "type": "contains", "target": "[group_instance_id]" }
  ],
  "meta": {
    "tool_instance_id": "[tool_instance_id]",
    "class_node_id": "[class_node_id]",
    "class_name": "[class name for display]",
    "status": "not_started",
    "allocation_locked": false,
    "approval_status": "pending",
    "teacher_node_id": null,
    "num_groups": 3
  }
}

Status values: not_started → active → submitted → approved

Group instances are now children of class_instance nodes, not tool_instance nodes directly. Update POST /api/tool-instances and the regenerate-groups endpoint accordingly.

Class assignment at project level

In the project wizard Step 3 (Participants), add a Classes section:

CLASSES ASSIGNED TO THIS PROJECT
[ + Assign class ]

11S1  ·  Mr J Clark  ·  ~30 students   [×]
9J1   ·  Ms Ahmed    ·  ~25 students   [×]

“+ Assign class” searches class nodes under this institution’s Students container. Selecting a class stores it in project.meta.assigned_classes: ["class_node_id"].

When the project is created, class assignment does NOT automatically create class_instance nodes under every tool instance — that happens at the tool instance level. Project-level assignment is just a pre-selection for convenience.

Class assignment at tool instance level

In the tool instance Setup tab, add a Class Assignment section above Group Configuration:

CLASSES DOING THIS TOOL

[ + Add class ]  (searches institution's classes, pre-selects project's assigned classes)

┌─────────────────────────────────────┐
│ 11S1  ·  Mr J Clark  ·  30 students │
│ Groups: 6  [configure →]  [×]       │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ 9J1   ·  Ms Ahmed  ·  25 students   │
│ Groups: 5  [configure →]  [×]       │
└─────────────────────────────────────┘

Adding a class here creates a class_instance node as a child of the tool instance, with group_instance children based on num_groups for that class.

Removing a class (×) deletes the class_instance node and all its group_instance children. Confirm first: “This will remove all groups and contributions for 11S1 from this tool instance. Are you sure?”

“Configure →” opens the group configuration for that class (replaces the current single-class group configuration in Setup tab).

Approval at class instance level

The class instance has its own approval state. The flow is:

Group contribution (pending)
  → approved by teacher/facilitator at class instance level
  → class instance status: submitted (all groups have ≥1 approved contribution)
  → approved by facilitator at tool instance level (cross-class review)
  → feeds into phase-level Collate

In the tool instance Contributions tab, add a class filter above the group filter:

[ All classes ] [ 11S1 ] [ 9J1 ]
[ All groups  ] [ Group 1 ] [ Group 2 ] ...

Class-level approval: a “Mark class as submitted” button appears in the class instance view when all groups in that class have ≥1 approved contribution. Sets class_instance.meta.status = “submitted”.

Verify Phase B

In project wizard, assign 11S1 and 9J1 to the project. project.meta.assigned_classes contains both class node ids.
In a tool instance Setup tab, both classes appear pre-selected. Adding a class creates a class_instance node under the tool instance. Each class_instance has group_instance children.
In the tool instance Contributions tab, class filter tabs appear. Filtering by 11S1 shows only 11S1’s contributions.
Removing a class from the tool instance (after confirmation) removes the class_instance and all its group_instance children from the tree.

PHASE C — Live Student Allocation

The allocation model

Students self-assign to groups using a group token on their device. Teachers can override any assignment. Teacher can lock allocation.

Authority hierarchy:

Student token → can self-assign if space available (role slots not full)
Teacher/facilitator → can assign/unassign any student, overrides student choice
Lock (teacher sets on class_instance) → freezes student self-assignment;
     only teacher can move students after lock

Role-based group size limit: Group capacity = number of roles defined on the tool instance’s steps meta. If a tool instance has roles: [Navigator, Sketcher, Note-taker, Interviewer], group capacity is 4. A student trying to join a full group sees: “This group is full (4/4 roles filled).” If no roles are defined, default capacity is the num_groups divisor (class size ÷ num_groups, rounded up).

Group token system

Each group_instance gets a short unique token on creation:

function generateGroupToken() {
  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // no ambiguous chars
  return Array.from({length: 6}, () =>
    chars[Math.floor(Math.random() * chars.length)]
  ).join('');
}

Token stored in group_instance.meta.token. Tokens are unique within a tool instance (check on generation).

Token login endpoint

POST /api/token-login
  body: { token }
  No auth required — this is the student entry point
  Finds the group_instance with matching meta.token
  Returns: {
    group_instance_id,
    group_name,
    class_instance_id,
    class_name,
    tool_instance_id,
    tool_name,
    institution_name,
    session_token   ← a short-lived session (24hr) with role: "group_token"
  }
  Sets cookie: lfti_group_session=<session_token>

Add group_token as a new role to the auth system. Group token sessions are stored in the sessions table with meta.group_instance_id and meta.class_instance_id.

A group_token session can:

View their class instance’s unallocated student list
Self-assign to their group (if space and not locked)
Add contributions to their group_instance (when allocation is complete)
View their group’s contributions and approval status
View class-example contributions

A group_token session cannot:

See other groups’ contributions
Access any other project, institution, or node
Approve contributions

Unallocated student list

The class instance carries the authoritative allocation state:

"meta": {
  ...
  "allocation": {
    "unallocated": ["Tom P", "Sarah K", "Amara D", ...],
    "locked": false
  }
}

When a class is assigned to a tool instance (Phase B), the unallocated list is populated from the class node’s student person nodes (first name + last initial). If no student roster exists for the class yet, unallocated list starts empty and students can add their name when joining via token.

Unallocated list API:

GET /api/class-instances/:id/allocation
  Returns: { unallocated: [...], groups: [{id, name, members, capacity}], locked: bool }
  Auth: any session with access to this class_instance (group_token, facilitator+)
  Polls every 10 seconds on the token login view

POST /api/class-instances/:id/assign
  body: { student_name, group_instance_id }
  Auth: group_token (can only assign to their own group if not locked)
        facilitator+ (can assign to any group)
  Validates: group not at capacity, not locked (unless facilitator+)
  Moves student_name from unallocated to group_instance.meta.members
  Returns: updated allocation state

POST /api/class-instances/:id/unassign
  body: { student_name, group_instance_id }
  Auth: group_token (can unassign from their own group if not locked)
        facilitator+ (can unassign from any group, ignores lock)
  Returns: updated allocation state

POST /api/class-instances/:id/lock
  body: { locked: true|false }
  Auth: facilitator+ only
  Sets class_instance.meta.allocation.locked
  Returns: { locked: bool }

Token login UI

A separate minimal page at /join — no main app chrome, no tree, no nav. URL: http://localhost:3000/join

┌─────────────────────────────────────────┐
│              LFTI                        │
│                                         │
│  Enter your group code                  │
│                                         │
│  [ X K 7 2 A 3           ]             │
│                                         │
│  [ Join →                ]             │
│                                         │
│  Ask your teacher for the code          │
│  printed on your group's worksheet.     │
│                                         │
└─────────────────────────────────────────┘

On successful token entry, show the group allocation view:

┌─────────────────────────────────────────┐
│ LFTI · Bristol Academy                  │
│ Transect Walk · 11S1 · Group 2          │
├─────────────────────────────────────────┤
│ WHO'S IN YOUR GROUP?                    │
│                                         │
│ Tap your name to join this group.       │
│ Not on the list? Type your name below.  │
│                                         │
│ UNALLOCATED (tap to join):              │
│ [ Tom P ] [ Sarah K ] [ Amara D ]      │
│ [ James W ] [ Priya N ] [ ...  ]       │
│                                         │
│ YOUR GROUP (Group 2):                   │
│ ✓ Marcus T  — Navigator                │
│ ✓ Yemi O    — Sketcher                 │
│ ○ [empty]   — Note-taker              │
│ ○ [empty]   — Interviewer             │
│                                         │
│ [2/4 members joined]  [Not locked]      │
│                                         │
│ [ I'm done — start the activity ]       │
│ (appears when ≥1 member in this group)  │
└─────────────────────────────────────────┘

Tapping a name in the unallocated list calls POST /api/class-instances/:id/assign. The list updates immediately on all polling devices (10s poll).

When teacher locks: unallocated list becomes read-only on group token devices. Show: “🔒 Groups are locked. Ask your teacher if you need to change groups.”

Teacher’s allocation view (in the tool instance Groups tab, per class):

11S1  ·  [🔒 Lock groups]  [Unlock]

UNALLOCATED (3):  Tom P · Sarah K · Amara D
  [Assign Tom P to: Group 1 ▾]  [Mark absent]

GROUP 1  (Navigator, Sketcher, Note-taker, Interviewer)
  ✓ Marcus T — Navigator       [move] [remove]
  ✓ Yemi O   — Sketcher        [move] [remove]
  ○ [empty]  — Note-taker
  ○ [empty]  — Interviewer

GROUP 2 ...

“Mark absent” removes from unallocated, sets person node meta.absent_this_session: true. Can be reversed.

Verify Phase C

Create a tool instance with 2 group token codes visible. Navigate to http://localhost:3000/join in an incognito window. Enter the group 1 token. See the allocation view with unallocated students.
Tap “Tom P” — Tom moves from unallocated to Group 1 on this device. Open another incognito window with the Group 2 token. Within 10 seconds, Tom P is gone from the unallocated list on Group 2’s device.
As facilitator in the main app, move Tom P from Group 1 to Group 2. Within 10 seconds, Group 1 token device shows Tom P gone from their group. Group 2 token device shows Tom P in their group.
Facilitator locks the class instance. Group token devices show the lock icon. Tapping unallocated names does nothing. Facilitator can still move students. Unlock restores self-assignment.
As facilitator, mark Sarah K as absent. Sarah K disappears from the unallocated list on all devices.

PHASE D — Cross-Class View & Feedforward to Collate

Tool instance cross-class view

When a tool instance has multiple class instances, the tool instance Contributions tab gains a class-level summary above the existing filters:

CLASSES  2

┌──────────────────────────────────┐  ┌──────────────────────────────────┐
│ 11S1                             │  │ 9J1                              │
│ 6 groups · 18 contributions      │  │ 5 groups · 12 contributions      │
│ ● submitted                      │  │ ○ in progress                    │
│ [View class →]                   │  │ [View class →]                   │
└──────────────────────────────────┘  └──────────────────────────────────┘

CROSS-CLASS VIEW
[ All ] [ 11S1 ] [ 9J1 ]    [ pending ] [ approved ] [ all ]

[contribution cards — filterable by class and approval status]

“View class →” navigates to the class_instance node (which has its own dedicated view — same tab pattern as tool instance: Groups / Contributions / Allocation / Summary).

Feedforward to Collate

When a Collate phase node is active, the phase panel (from Phase 3) already shows a “From Gather” section. Extend this to show contributions at the class instance level:

FROM GATHER

[ All classes ] [ 11S1 ] [ 9J1 ]    Show: [ approved only ● ] [ all ○ ]

[contribution cards from the matching Gather tool instances]
[each card shows: group name, class name, content preview, approval status]

The Collate class instance (when a class does Collate) sees:

Primary: their own class’s approved Gather contributions (auto-surfaced)
Secondary: other classes’ approved Gather contributions (available to browse and include via a “bring into our Collate” action)

“Bring into our Collate” creates a responds_to relation from the Collate class instance to the selected Gather contribution node. It appears in their Collate view marked as “included from [class name]”.

Verify Phase D

Two class instances on one tool instance, both with approved contributions. Tool instance Contributions tab shows the class summary cards with counts. Class filter tabs show contributions from each class separately.
Navigate to a Collate phase node. “From Gather” section shows contributions filterable by class. 11S1’s contributions are shown by default.
Click “bring into our Collate” on a 9J1 contribution. It appears in the Collate view marked “included from 9J1”. A responds_to relation is created in the graph.

What does NOT change

Reference instance — unchanged
Auth system (except adding group_token role) — unchanged
Image maps — unchanged
Temporal navigation — unchanged
Standard node view — unchanged (accessible via node view ↗ on all custom views)
Quick capture — unchanged

File changes

db/database.js          — migrations table, inst_hierarchy_v1,
                          project_container_v1, group token generation
api/institutions.js     — POST /api/institutions (new)
api/class-instances.js  — GET/POST allocation, assign, unassign, lock (new)
api/auth.js             — group_token role, POST /api/token-login (new)
api/tool-instances.js   — class_instance creation, regenerate-groups update
api/projects.js         — institution scoping enforcement, assigned_classes
server.js               — mount new routers, serve /join route
lfti-spine.html         — class assignment in Setup tab, cross-class view,
                          teacher allocation view, feedforward Collate section,
                          container node rendering
public/join.html        — NEW: minimal token login page (separate from main app)

Note: /join is a separate minimal HTML file served at that route. It does not share the main app’s JS — it only needs: token input, POST /api/token-login, allocation polling (GET /api/class-instances/:id/allocation), assign/unassign calls, and a simple contribution upload for when allocation is done. Keep it under 400 lines. Style to match the main app’s design tokens via a shared CSS variables approach (serve the same CSS variables, minimal additional styles).

When you’re done — full verification

Run through this sequence across multiple browser windows:

Phase A: Superadmin creates Bristol Academy. Staff/Students/Projects containers appear. Bristol Academy admin logs in, can only create projects under Bristol Academy.
Phase B: Project wizard pre-selects assigned classes. Tool instance Setup tab shows class assignment section. Adding 11S1 creates a class_instance with group children. Removing it (after confirmation) cleans up completely.
Phase C: Two group tokens visible on a tool instance. Navigate to /join in incognito. Enter token. See allocation view. Self-assign. Second incognito window with other group token sees the change within 10 seconds. Facilitator locks — self-assignment blocked on token devices.
Phase D: Two classes with approved contributions on one tool instance. Cross-class summary cards visible. Collate phase feedforward shows both classes’ contributions filterable and includable.

Minimal authentication system

2026-05-21T00:00:00.000Z

This prompt adds user authentication to the LFTI spine. Read the existing codebase fully before starting — particularly server.js, db/database.js, and api/nodes.js. Understand what exists before adding to it.

The goal is the smallest correct auth system that supports role-based access and institution scoping, is easy to extend later, and doesn’t break anything currently working.

Design principles (do not violate)

Simple over complete. No OAuth, no email verification, no password reset flow yet. Those come later. Build what’s needed now.
Additive only. Nothing currently working should break. The API endpoints continue to work. The frontend continues to load. Auth wraps the existing system, it doesn’t replace it.
Users are also nodes. Every user has a corresponding node in the graph with type: "person". The user table is the auth layer only — all relationships live in the graph.
Escape hatch preserved. The meta{} field on the user table follows the same convention as nodes.
Local dev friendly. Must be testable with multiple users from one machine using different browsers or incognito windows.

Database changes

Add to db/database.js:

CREATE TABLE IF NOT EXISTS users (
  id             TEXT PRIMARY KEY,
  name           TEXT NOT NULL,
  email          TEXT UNIQUE NOT NULL,
  password_hash  TEXT NOT NULL,
  role           TEXT NOT NULL DEFAULT 'student',
  institution_id TEXT,
  node_id        TEXT,
  created_at     TEXT NOT NULL,
  meta           TEXT DEFAULT '{}'
);

CREATE TABLE IF NOT EXISTS sessions (
  token          TEXT PRIMARY KEY,
  user_id        TEXT NOT NULL,
  created_at     TEXT NOT NULL,
  expires_at     TEXT NOT NULL,
  FOREIGN KEY (user_id) REFERENCES users(id)
);

CREATE INDEX IF NOT EXISTS idx_sessions_user ON sessions(user_id);
CREATE INDEX IF NOT EXISTS idx_users_email ON users(email);

Roles (stored as strings, checked in middleware):

superadmin — sees everything, can create institutions and users
institution_admin — manages their institution’s projects and users
facilitator — runs sessions within projects they’re assigned to
student — contributes to sessions they’re part of
observer — read-only access to approved artefacts

Password hashing: Use bcrypt with 10 salt rounds. Add bcrypt to package.json dependencies.

Session tokens: Generate with crypto.randomBytes(32).toString('hex'). Sessions expire after 7 days. Clean up expired sessions on server start.

Seed users for development

On first run (if users table is empty), seed these development users automatically so the system is immediately testable:

const devUsers = [
  {
    id: 'user_superadmin',
    name: 'Super Admin',
    email: 'admin@lfti.dev',
    password: 'lfti-admin',
    role: 'superadmin',
    institution_id: null,
    node_id: 'person_admin'
  },
  {
    id: 'user_uk_admin',
    name: 'UK School Admin',
    email: 'ukadmin@lfti.dev',
    password: 'lfti-uk',
    role: 'institution_admin',
    institution_id: 'uk',       // matches existing institution node
    node_id: 'person_uk_admin'
  },
  {
    id: 'user_facilitator',
    name: 'James (Facilitator)',
    email: 'facilitator@lfti.dev',
    password: 'lfti-facilitator',
    role: 'facilitator',
    institution_id: 'uk',
    node_id: 'person_facilitator'
  },
  {
    id: 'user_student_1',
    name: 'Student One (UK)',
    email: 'student1@lfti.dev',
    password: 'lfti-student',
    role: 'student',
    institution_id: 'uk',
    node_id: 'person_student_1'
  },
  {
    id: 'user_zm_admin',
    name: 'Kamoto Admin',
    email: 'zmadmin@lfti.dev',
    password: 'lfti-zm',
    role: 'institution_admin',
    institution_id: 'zm',       // matches existing institution node
    node_id: 'person_zm_admin'
  },
  {
    id: 'user_observer',
    name: 'Observer (Funder)',
    email: 'observer@lfti.dev',
    password: 'lfti-observer',
    role: 'observer',
    institution_id: null,
    node_id: 'person_observer'
  }
];

Print all dev credentials to the console on first seed so they’re easy to find:

╔══════════════════════════════════════════╗
║     LFTI Dev Users — First Run Seed      ║
╠══════════════════════════════════════════╣
║ superadmin      admin@lfti.dev           ║
║ institution_admin ukadmin@lfti.dev       ║
║ facilitator     facilitator@lfti.dev     ║
║ student         student1@lfti.dev        ║
║ zm admin        zmadmin@lfti.dev         ║
║ observer        observer@lfti.dev        ║
║ (all passwords in db/database.js seed)   ║
╚══════════════════════════════════════════╝

Also create corresponding person nodes in the graph for each dev user, with involves relations to their institution nodes where applicable.

New files

`api/auth.js`

Handles all auth routes:

POST /api/auth/login
  body: { email, password }
  response: { user: { id, name, role, institution_id, node_id }, token }
  sets httpOnly cookie: lfti_session=<token>
  on failure: 401 { error: "Invalid credentials" }

POST /api/auth/logout
  clears cookie, deletes session token from db
  response: { ok: true }

GET /api/auth/me
  reads cookie, returns current user or 401
  response: { user: { id, name, role, institution_id, node_id } }
  this is what the frontend calls on boot to check if logged in

Cookie settings:

res.cookie('lfti_session', token, {
  httpOnly: true,
  sameSite: 'lax',
  maxAge: 7 * 24 * 60 * 60 * 1000,  // 7 days in ms
  // secure: true  // uncomment when running over HTTPS
});

`middleware/auth.js`

Two middleware functions used by API routes:

// requireAuth — rejects unauthenticated requests
function requireAuth(req, res, next) { ... }

// requireRole(...roles) — rejects users without matching role
function requireRole(...roles) {
  return (req, res, next) => { ... }
}

Both attach req.user (the full user row) when successful.

Usage in routes:

const { requireAuth, requireRole } = require('../middleware/auth');

router.get('/api/nodes', requireAuth, (req, res) => { ... });
router.delete('/api/nodes/:id', requireAuth, requireRole('facilitator', 'institution_admin', 'superadmin'), (req, res) => { ... });

Institution scoping

When a non-superadmin user requests nodes, filter by institution visibility:

A node is visible to a user if ANY of the following:

The node’s meta._visibility is "public" or "portal"
The node’s meta._visibility is "partners" and the user’s institution has an involves or responds_to relation to the node or its project ancestor
The node has no _visibility set (defaults to private) AND the node belongs to the user’s institution (determined by traversing contains relations up to an institution node)
The user is superadmin
The node’s meta._level is "reference" (reference nodes are always visible to authenticated users)

Implementation: Add a filterNodesByVisibility(nodes, user) function in db/database.js. Call it in GET /api/nodes after fetching all nodes.

For this first pass, implement rules 1, 4, 5, and a simplified version of 3 (nodes whose institution_id meta field matches the user’s institution_id). Rules 2 and the full graph traversal version of 3 can come later — add a comment marking where that logic goes.

Frontend changes

Login screen

When the app loads and GET /api/auth/me returns 401, show a login screen instead of the main UI. The login screen replaces the full app — not a modal, not an overlay, a full page replacement.

LFTI logo / wordmark (same styling as the header)
Email input
Password input
Login button
Error message area (shows “Invalid credentials” on failure)
No registration link — accounts are created by admins

On successful login: hide login screen, show main app, initialise normally (call loadDB() etc.)

Style to match existing design language exactly — var(--bg), var(--surface), var(--accent), var(--mono) font. The login screen should feel like part of the same system, not a different product.

User context in the app

After login, the frontend holds the current user in state:

state.currentUser = {
  id, name, role, institution_id, node_id
};

Use this to:

Show/hide controls based on role:

Delete button in footer: hide for student and observer
+ capture button: hide for observer
Type pills: hide for observer
+ map image button: hide for observer

Show user identity in the header: Add a small user indicator to the right of the header (before the search input):

[role badge] [name]  [logout]

Role badge styling:

superadmin → accent colour
institution_admin → muted blue
facilitator → muted orange
student → muted green
observer → text-dim

Logout: clicking logout calls POST /api/auth/logout, clears state.currentUser, shows login screen.

API calls with auth

All existing fetch calls to /api/ already work with cookies because cookies are sent automatically with same-origin requests. No changes needed to the fetch calls themselves — the httpOnly cookie is sent by the browser on every request.

However: wrap the boot sequence so it waits for GET /api/auth/me before calling loadDB(). If auth fails, show login screen. If auth succeeds, store user in state and proceed normally.

async function boot() {
  try {
    const res = await fetch('/api/auth/me');
    if (!res.ok) { showLoginScreen(); return; }
    const { user } = await res.json();
    state.currentUser = user;
    seedLFTI();
    seedReferenceInstance();
    loadDB();
    saveDB();
    renderTree();
    updateStatus();
    renderTemporalNav();
    renderUserBadge();
  } catch(e) {
    showLoginScreen();
  }
}

boot();

Route protection in server.js

Apply requireAuth to all /api/nodes routes. Apply requireAuth to all /api/images routes. Leave /api/auth/login and /api/auth/logout and /api/auth/me unprotected (they are the auth routes themselves). Leave the static file serving (the HTML file) unprotected — the frontend handles the auth check on load.

package.json additions

Add one dependency:

"bcrypt": "^5.1.1"

No other new packages. crypto is built into Node.js.

File structure after this prompt

/
├── api/
│   ├── nodes.js         (modified — add requireAuth)
│   ├── images.js        (modified — add requireAuth)
│   └── auth.js          (new)
├── middleware/
│   └── auth.js          (new)
├── db/
│   └── database.js      (modified — users table, sessions table, dev seed)
├── codeReference/
│   └── ...              (unchanged)
├── server.js            (modified — mount auth routes, apply middleware)
└── lfti-spine.html      (modified — login screen, boot sequence, user badge)

Testing checklist — do all six before finishing

Open Chrome. Go to http://localhost:3000. See login screen (not the app).
Login as admin@lfti.dev / lfti-admin. See the app with superadmin badge in header. All controls visible. All nodes visible including reference instance.
Open Firefox (or incognito). Login as student1@lfti.dev / lfti-student. See app with student badge. Delete button hidden. Capture button visible. Only UK institution nodes visible (not Zambia private nodes).
Open Edge (or second incognito). Login as observer@lfti.dev / lfti-observer. See app with observer badge. Delete hidden, capture hidden, type pills hidden. Only public/portal visibility nodes visible.
Click logout in any browser. Login screen appears. App state is cleared.
Close browser entirely (not just the tab). Reopen http://localhost:3000. Session cookie persists — app loads directly without login screen (7-day cookie). Verify correct user is still recognised via GET /api/auth/me.

Phase 3 — project dashboard and tool selection

2026-05-21T00:00:00.000Z

This prompt builds on the completed project setup wizard. Read the full codebase before starting. Understand the existing node structure, the phase node meta fields (movement, phase, status), the reference instance tool nodes, and the current content section rendering in lfti-spine.html.

This prompt has two distinct pieces:

Project node → dashboard view
Phase node → tool browser + session launcher

Build and verify piece 1 before starting piece 2.

PIECE 1 — Project Dashboard

When a node of type project is selected, render a dashboard instead of the standard parents/this node/children layout. The standard layout remains accessible via a small “← node view” link in the dashboard header for power users.

Dashboard layout

┌─────────────────────────────────────────────────────────────────┐
│ [Project title]                    [● Active]  [node view ↗]   │
│ [institution name] · [date range] · [format]                    │
├─────────────────────────────────────────────────────────────────┤
│ TABS: [ Overview ] [ Approvals n ] [ Participants ] [ Settings ]│
├─────────────────────────────────────────────────────────────────┤
│ [tab content — see below]                                        │
└─────────────────────────────────────────────────────────────────┘

Status badge colours (using existing CSS variables):

not_started → var(--text-dim) · label: “Not started”
active → var(--accent) · label: “Active”
complete → muted blue · label: “Complete”
archived → var(--text-dim) · label: “Archived”

Overview tab

Three sections:

Progress grid:

PROGRESS

              Gather          Collate         Present
Past          [●●●○○  3]     [○○○○○  0]     [○○○○○  0]
Situation     [○○○○○  0]     [○○○○○  0]     [○○○○○  0]
Futures       [○○○○○  0]     [○○○○○  0]     [○○○○○  0]
Whole         [○○○○○  0]     [○○○○○  0]     [○○○○○  0]

Each cell is clickable — navigates to that phase node via selectNode(). The number shown is the count of direct child nodes of that phase node (i.e. contribution/artefact nodes created under it). Filled dots scale: 0=empty, 1-2=one dot, 3-4=two dots, 5+=three dots (out of five dot positions).

Each cell has a subtle status colour:

No children, no tool selected → dim (not started)
Tool selected but no contributions → amber (in progress / waiting)
Has contributions, not approved → amber
Has approved contributions → accent green

Needs attention: A list of items requiring action from this user. Only show items relevant to their role. Empty state: “Nothing needs attention right now.”

Items to surface:

“n contributions awaiting approval” → links to Approvals tab
“[Phase name] has no tool selected” → links to that phase node
“Workshop date [date] is tomorrow — [phase] is not started”
“Partner institution has shared new content” (when interchange exists)

Each item has a small arrow link → navigating to the relevant node or tab.

Participants summary:

PARTICIPANTS
  2 staff  ·  2 classes (11S1, 9J1)  ·  ~30 students
  [ Manage participants → ]

Manage participants link navigates to the Participants tab.

Approvals tab

Only visible to facilitator, institution_admin, superadmin roles. Badge on tab shows count of pending approvals.

Standard mode (default): A list of pending contributions. Each item shows:

Group name / contributor
Phase (e.g. “Past — Gather”)
Tool used
Timestamp
Content preview (title + first line of body, or thumbnail if image)
[ Approve ] [ Flag ] buttons

Approve: sets node.meta.approval_status = "approved", saves via PUT /api/nodes/:id Flag: opens a small inline text field for a note, sets node.meta.approval_status = "flagged", sets node.meta.flag_note = "[text]", saves. Flagged content is visible to the group with the note displayed.

Empty state: “No contributions awaiting approval.”

Live session mode: A toggle button in the top right of the Approvals tab: “[ ○ Live mode ]” When activated:

Tab background shifts slightly (subtle amber tint on the tab itself)
List becomes a real-time feed — poll GET /api/projects/:id/pending every 5 seconds
New items animate in at the top
Approve button is larger and more prominent
A “Live session active” indicator appears in the header status area

Add endpoint:

GET /api/projects/:id/pending
  Returns all child nodes of this project's phase nodes where 
  meta.approval_status is null or "pending"
  Ordered by created_at desc
  Auth: facilitator+ only

Participants tab

Three sections matching the wizard Step 3:

Staff & facilitators — list with role badge, remove button Classes — list with class name, teacher, student count, remove button Groups — auto-suggested groups per class, editable names

+ Add staff, + Add class buttons open small inline forms (not the full wizard). Changes save immediately via PUT /api/nodes/:id on the relevant person/session node.

Settings tab

Editable fields:

Project name
Description
Date range (start/end)
Workshop dates (add/remove)
Approval mode toggle (Standard / Live)
Group contribution limit (number input)
Archive project button (sets status to archived, confirms first)

All changes save via PUT /api/nodes/:id on the project node’s meta.

PIECE 2 — Phase Node: Tool Browser & Session Launcher

When a node with meta.phase set (gather/collate/present) is selected, replace the empty children section with a purposeful phase panel.

Phase panel layout

┌─────────────────────────────────────────────────────────────────┐
│ PAST — GATHER                                    [status badge] │
│ Students explore and capture their experience of the past.      │
│ (pulled from the matching reference phase node body)            │
├─────────────────────────────────────────────────────────────────┤
│ TOOLS FOR THIS PHASE                                            │
│                                                                 │
│ Filters: [Individual] [Group] [Indoors] [Outdoors] [Async]     │
│          [Sync] [< 30min] [30-60min] [60min+]                  │
│          [Low-tech] [High-tech]                                 │
│                                                                 │
│ [tool card] [tool card] [tool card]                             │
│ [tool card] [tool card] [+ more]                                │
│                                                                 │
│ Selected: Body Map ×   Story Circle ×   [+ add another]        │
│                                                                 │
│ [ Start this phase → ]  (appears when ≥1 tool selected)        │
├─────────────────────────────────────────────────────────────────┤
│ CONTRIBUTIONS  0                                                │
│ (empty state until session is started)                          │
└─────────────────────────────────────────────────────────────────┘

Tool cards

Each card represents a reference tool node matching this phase. Pull tool nodes from the reference instance where meta.phase matches the current phase node’s meta.phase value.

Card shows:

Tool title (truncated if long)
2-line description excerpt from node body
Small badges: individual/group, indoor/outdoor, time estimate
Selected state: accent border + checkmark when selected

Clicking a card toggles selection. Maximum selection: no hard limit, but after 3 selected show a gentle nudge: “You have 3 tools selected — that’s a full session. Add more if you need, or start now.” The nudge disappears after 5 seconds or on dismissal.

Tool filters

Filter buttons are toggle pills above the tool grid. Multiple can be active simultaneously — show tools matching ALL active filters (AND logic). Clearing all filters shows all tools for this phase.

Filter values come from tool node meta fields. Add these meta fields to reference tool nodes during this prompt (update the existing seeded nodes):

"meta": {
  "_level": "reference",
  "_visibility": "public",
  "phase": "gather",
  "format": ["group", "individual"],       // can be both
  "location": ["indoors", "outdoors"],     // can be both  
  "modality": ["sync", "async"],           // can be both
  "duration": "60min+",                    // "< 30min" | "30-60min" | "60min+"
  "tech_level": "low"                      // "low" | "high" | "both"
}

Update all reference tool nodes with appropriate values based on PLA_TOOLS_REFERENCE.md descriptions. Do not guess — if a field is genuinely ambiguous for a tool, use both values or omit the filter tag.

Starting a phase

“Start this phase →” button:

Sets phase_node.meta.status = "active", saves
Sets phase_node.meta.selected_tools = ["ref_g_body_map", "ref_g_story_circle"] (array of selected reference tool node ids)
Adds references relations from phase node to each selected tool node
Shows the contributions area (was empty/hidden before)
Updates the project dashboard progress grid cell for this phase to amber

The phase node now shows the session launcher area below the tool section:

Contributions area (after phase started)

CONTRIBUTIONS  0          [ + Add contribution ]   [ ⚡ Live mode ]

Groups:  [ All ] [ Group 1 ] [ Group 2 ] [ Group 3 ]

(empty state)
"No contributions yet. Groups can add their work using the button above 
or from their own view."

+ Add contribution button: opens the quick-capture overlay pre-configured for this phase — type set to artefact, parent set to this phase node, meta.phase and meta.movement inherited, meta.approval_status = "pending".

Group filter tabs: filter displayed contributions by the contributing group node.

Each contribution card shows:

Title
Contributor (group name)
Timestamp
Approval status badge: pending / approved / flagged
If flagged: the flag note
Click → selectNode() to view the full contribution node

For facilitator/admin: Approve and Flag buttons inline on each card. For students: their own group’s contributions only, with approval status visible.

Collate phase special behaviour

When meta.phase === "collate", the tool browser shows Collate tools. Additionally, above the tool browser, show a “From Gather” section:

FROM GATHER
[contribution card] [contribution card] [contribution card]
(approved contributions from the matching Gather phase node)
"These are the findings your group produced in Gather. 
Use them as the starting point for Collate."

Pull these by finding the sibling Gather phase node (same movement, phase: “gather”) and showing its approved children.

Present phase special behaviour

When meta.phase === "present", the tool browser shows Present tools. Additionally, above the tool browser, show a “From Collate” section showing approved Collate outputs, same pattern as above.

If a partner institution exists on this project, show:

EXCHANGE
This project is paired with [partner institution].
Approved Present artefacts will be visible to them.
[ View their Present artefacts → ]  (links to partner's present phase node)

Reference tool node meta updates

Update ALL reference tool nodes in the database with appropriate filter meta values. Do this via a migration script scripts/update_tool_meta.js that can be run with node scripts/update_tool_meta.js.

Use these values as a guide (fill in all tools from PLA_TOOLS_REFERENCE.md):

Tool	format	location	modality	duration	tech_level
Observation	individual	both	both	30-60min	low
Semi-structured interview	both	both	both	60min+	low
Transect walk	group	outdoors	sync	60min+	low
Body map	both	indoors	sync	60min+	low
Photo walk	both	both	sync	30-60min	both
Story circle	group	indoors	sync	30-60min	low
River of life	individual	indoors	both	30-60min	low
Peer interview	individual	both	both	30-60min	low
Learning journal	individual	both	async	<30min	low
Timeline	both	indoors	sync	30-60min	low
Focus group	group	indoors	sync	60min+	low
Pre-perceptions	individual	indoors	sync	<30min	low
Stones in circles	group	both	sync	30-60min	low
Matrix ranking	group	both	sync	30-60min	low
Pairwise ranking	group	indoors	sync	30-60min	low
Body voting	group	both	sync	<30min	low
Affinity grouping	group	indoors	sync	30-60min	low
Venn diagram	group	both	sync	60min+	low
Causal flow diagram	group	both	sync	60min+	low
Spectrum line	group	both	sync	<30min	low
Most significant change	both	both	both	30-60min	low
Live performance	group	both	sync	60min+	low
Transect walk as presentation	group	outdoors	sync	60min+	low
Exhibition	group	both	both	60min+	both
Short video	both	both	async	30-60min	high
Podcast	both	both	async	30-60min	high
Zine	both	indoors	async	60min+	both
Story of self	individual	both	both	<30min	low
Pre-perceptions delta	both	indoors	sync	30-60min	low
Hot seating	group	indoors	sync	30-60min	low

New API endpoints

GET /api/projects/:id/pending
  Returns pending contributions for facilitator approval
  Auth: facilitator+

GET /api/projects/:id/progress  
  Returns contribution counts per phase for the progress grid
  { past_gather: 3, past_collate: 0, ... }
  Auth: any authenticated user with access to this project

What does NOT change

Tree navigation, position mode, graph mode — unchanged
Quick capture overlay (used as base for contribution capture) — unchanged
Auth system — unchanged
Reference instance nodes (except adding filter meta fields) — otherwise unchanged
Standard node view for non-project, non-phase nodes — unchanged
Image maps, temporal nav — unchanged

File changes

lfti-spine.html     — project dashboard UI, phase panel UI
api/projects.js     — add /pending and /progress endpoints  
scripts/
  update_tool_meta.js  — one-time migration to add filter meta to tool nodes

When you’re done — test in order

Click the project node as ukadmin. See the dashboard with Overview tab showing the progress grid (all empty/dim), no needs-attention items, participant summary.
Click “Past — Gather” phase node. See the tool browser with filter pills and tool cards. Click “Group” filter — only group tools remain. Click a tool card to select it. Select two more. See the nudge appear. See “Start this phase →” button.
Click “Start this phase →”. Phase status changes to active. Progress grid cell updates to amber. Contributions area appears (empty).
Click “+ Add contribution”. Quick-capture opens pre-filled for this phase. Save a test contribution. It appears in the contributions area with “pending” badge.
As ukadmin in the dashboard Approvals tab, see the pending contribution. Click Approve. Contribution badge changes to “approved”. Progress grid cell updates to green.
Navigate to “Past — Collate”. See the “From Gather” section showing the approved contribution from step 5.

Project setup flow

2026-05-21T00:00:00.000Z

This prompt builds the guided project setup experience for new institutional users. Read the full codebase before starting — particularly the existing node structure, the auth system, and how institution/project/cycle nodes are currently seeded in seedLFTI().

The goal: a teacher or facilitator at a new school can go from first login to a working project skeleton in under 2 minutes. Everything inferrable is pre-populated. Everything non-essential has a sensible default. Details can be added later.

Design principles for this feature

Speed over completeness. The setup flow must be fast. A teacher has 5 minutes before a class. Pre-populate aggressively. Make every field optional except the bare minimum to create the structure.

The right thing should be the obvious thing. In Zambia and elsewhere, excellent facilitators may find the tech challenging. The UI must make correct process hard to avoid and the next step always clear.

Group contributions as the default. The system nudges toward group work (4–6 students per group) rather than individual contributions. This reduces the approval bottleneck and matches the participatory methodology.

Approval protects without blocking. Student content is visible within the project immediately but requires teacher/facilitator approval before publishing externally. This is the default (async). A live session mode (sync) is available as a toggle.

Nodes are still the underlying structure. The setup wizard creates real nodes — institution, project, staff, class, cycle, phase nodes — using the existing API. The wizard is a friendly skin over node creation, not a separate system.

Institution landing page

When an institution_admin or facilitator logs in and their institution node exists but has no project nodes under it, the landing page (content area when the institution node is selected) shows:

┌─────────────────────────────────────────────────────┐
│                                                     │
│   Welcome to LFTI                                   │
│   [institution name]                                │
│                                                     │
│   ┌─────────────────────────────────────────────┐   │
│   │         + Start Your First Project          │   │
│   │         (large, accent colour, dominant)    │   │
│   └─────────────────────────────────────────────┘   │
│                                                     │
│   Complete your institution profile  →              │
│   (smaller, secondary, below the main button)       │
│                                                     │
└─────────────────────────────────────────────────────┘

Once at least one project exists, the institution landing page shows:

Active projects as cards (title, status, date range, participant count)
A smaller + New Project button in the top right of the projects section
Creating a node of type project under the institution node also triggers the setup wizard

Project setup wizard

A full-screen overlay (same pattern as quick-capture but larger). Five steps, shown as a progress indicator at the top. Each step has a Back and Next button. Final step has a Launch Project button.

Progress indicator:

① Project basics  ② Schedule  ③ Participants  ④ Format  ⑤ Review

Clicking a completed step navigates back to it. Incomplete future steps are greyed out.

Step 1 — Project basics

Fields:

Project name (text, required) — pre-populated with “[Institution name] — LFTI [current year]”
Description (textarea, optional) — placeholder: “What is this project about? Who is involved? You can add this later.”
Country context (auto-detected from institution node’s context tag — uk / nz / zambia / other) — shown as a read-only badge, editable if wrong
Partner institution (optional) — search existing institutions by name. If selected, marks this as a paired project. Can be added later.

Pre-population logic:

Institution name comes from the logged-in user’s institution_id → institution node title
Year comes from current date
Country context comes from institution node meta.context

Step 2 — Schedule

Fields:

Project format (segmented control, required):
- Intensive week — one continuous week
- Weekly sessions — one session per week over a half-term or term
- Custom — define your own structure
Start date (date picker, required) — defaults to next Monday
End date (date picker, required) — auto-calculated based on format:
- Intensive week: start + 5 days
- Weekly sessions: start + 6 weeks
- Custom: user sets manually
Workshop dates (appears after start/end are set) — a simple list of specific dates within the range. Pre-populated based on format:
- Intensive week: Mon–Fri of the start week
- Weekly sessions: same day each week for 6 weeks
- Custom: empty, user adds dates manually
Each date can have a label (e.g. “Day 1 — Past Gather”) — pre-populated with sensible defaults, editable.
Academic calendar (select, optional) — UK / NZ / Zambia / Custom. Auto-detected from country context. Used for display formatting of dates.

Step 3 — Participants

Three sections, each collapsible:

Staff & facilitators:

Add by name + email (they’ll get an invite — invite system is a placeholder for now, just store the email in the person node’s meta)
Role: institution_admin / facilitator (select)
Pre-populated with the logged-in user

Classes:

Add class name (e.g. “Year 9 — 9A”, “Form 3 North”)
Class teacher name + email (optional — can add later)
Approximate student count (number input, optional) — used to suggest group sizes
Multiple classes can be added with + Add another class

Groups (within classes):

Auto-suggested based on student count: “Based on [n] students, we suggest [n/5 rounded up] groups of 4–5”
Groups can be named or left as Group 1, Group 2 etc
Students self-assign to groups within the app (organic — not set up by admin)
Soft content limit per group: 5 contributions per tool phase (shown as a nudge, not a hard block)

Minimum viable: Just the logged-in user as a participant is enough to proceed. Everything else can be added later.

Step 4 — Format

This step configures the cycle structure and approval settings.

Movements to include (multi-select, all selected by default):

☑ Past
☑ Situation
☑ Futures
☑ Whole (auto-includes, greyed out with tooltip: “The Whole cycle draws from all three movements”)

Approval mode:

Content approval

○ Standard (recommended)
  Student group content is visible within your project immediately.
  You approve before it's shared externally.
  Good for: most classroom situations, when you're also facilitating.

○ Live session mode
  You see uploads in real time and approve as they come in.
  Good for: whiteboard sessions with a co-facilitator.
  
  You can switch between modes at any time during the project.

Group contribution soft limit:

Suggested contributions per group per phase: [5] (editable number)
Groups will see a nudge when they reach this limit.
They can add more, but are encouraged to prioritise first.

International exchange: If a partner institution was selected in Step 1, show:

☑ Enable story interchange with [partner institution name]
  Students will be able to see and respond to each other's 
  approved Present artefacts.

Step 5 — Review

A clean summary of everything configured:

PROJECT
  Name: [name]
  Institution: [institution]
  Partner: [partner or "standalone"]
  
SCHEDULE  
  Format: [format]
  Dates: [start] → [end]
  Sessions: [n] workshop dates

PARTICIPANTS
  Staff: [n]
  Classes: [n] ([total students approx])
  Groups: [n groups suggested]

STRUCTURE
  Movements: Past, Situation, Futures, Whole
  Phases per movement: Gather → Collate → Present
  Total cycle nodes: 12

APPROVAL
  Mode: Standard / Live session
  Group limit: [n] contributions per phase

[ Back ]                    [ Launch Project → ]

Launch Project button:

Creates all nodes (see Node generation below)
Shows a brief “Building your project…” animation (just a spinner with the text)
Navigates to the new project node on completion
The project node’s content area shows the project dashboard (see below)

Node generation on Launch

The wizard creates the following nodes via the existing PUT /api/nodes/:id endpoint:

Project node:

{
  "id": "proj_[timestamp]",
  "type": "project",
  "title": "[project name]",
  "parent_ids": ["[institution_id]"],
  "relations": [
    { "type": "hosts", "target": "[institution_id]" }
  ],
  "meta": {
    "status": "active",
    "format": "intensive_week|weekly|custom",
    "start_date": "ISO date",
    "end_date": "ISO date",
    "workshop_dates": ["ISO date", ...],
    "academic_calendar": "uk|nz|zambia|custom",
    "approval_mode": "standard|live",
    "group_limit": 5,
    "country_context": "uk|nz|zambia|other"
  }
}

Four movement nodes (Past, Situation, Futures, Whole):

{
  "id": "mov_[proj]_past",
  "type": "cycle",
  "title": "Past",
  "parent_ids": ["proj_[timestamp]"],
  "relations": [
    { "type": "contains", "target": "phase_[proj]_past_gather" },
    { "type": "sequence", "target": "mov_[proj]_situation" },
    { "type": "references", "target": "ref_g_phase" }
  ],
  "meta": {
    "movement": "past",
    "status": "not_started"
  }
}

Twelve phase nodes (3 phases × 4 movements):

{
  "id": "phase_[proj]_past_gather",
  "type": "session",
  "title": "Past — Gather",
  "parent_ids": ["mov_[proj]_past"],
  "relations": [
    { "type": "sequence", "target": "phase_[proj]_past_collate" },
    { "type": "references", "target": "ref_g_phase" }
  ],
  "meta": {
    "movement": "past",
    "phase": "gather",
    "status": "not_started",
    "approval_mode": "standard"
  }
}

The feeds relations for Whole cycle:

{ "type": "feeds", "target": "phase_[proj]_whole_gather", "from": "phase_[proj]_past_present" }
{ "type": "feeds", "target": "phase_[proj]_whole_gather", "from": "phase_[proj]_situation_present" }
{ "type": "feeds", "target": "phase_[proj]_whole_gather", "from": "phase_[proj]_futures_present" }

Person nodes for staff added in Step 3:

{
  "id": "person_[timestamp]",
  "type": "person",
  "title": "[name]",
  "parent_ids": ["proj_[timestamp]"],
  "relations": [{ "type": "involves", "target": "proj_[timestamp]" }],
  "meta": {
    "role": "facilitator|institution_admin",
    "email": "[email]",
    "invite_status": "pending"
  }
}

Class nodes:

{
  "id": "class_[timestamp]",
  "type": "session",
  "title": "[class name]",
  "parent_ids": ["proj_[timestamp]"],
  "relations": [{ "type": "involves", "target": "proj_[timestamp]" }],
  "meta": {
    "student_count": n,
    "suggested_groups": n,
    "teacher_email": "[email]"
  }
}

Project dashboard (post-launch view)

When a project node is selected, its content section shows a project dashboard instead of the standard parents/content/children layout.

The dashboard has two views, toggled by a small tab:

Overview tab (default):

[Project name]                    [Standard mode ▾]  [⚙ Settings]

PROGRESS
Past        [Gather ●●●○○] [Collate ○○○○○] [Present ○○○○○]
Situation   [Gather ○○○○○] [Collate ○○○○○] [Present ○○○○○]  
Futures     [Gather ○○○○○] [Collate ○○○○○] [Present ○○○○○]
Whole       [Gather ○○○○○] [Collate ○○○○○] [Present ○○○○○]

● = contributions uploaded  ○ = empty

NEEDS ATTENTION
  ▶ 3 group contributions awaiting your approval   [Review →]
  ▶ Situation — Gather has no tool selected yet    [Choose tool →]

PARTICIPANTS
  2 staff  ·  1 class  ·  6 groups  ·  ~30 students
  [Manage →]

UPCOMING
  Day 2 — Past Collate    Tomorrow
  Day 3 — Past Present    Thursday

Approval tab (shows when approval_mode is standard):

A list of pending contributions — group name, tool used, phase, timestamp. Each has an Approve and Flag button. Flagged contributions go back to the group with a note.

Live session mode toggle: When switched to live mode, the approval tab becomes a real-time feed — contributions appear as they’re uploaded. A large Approve button dominates. Designed for a facilitator watching a whiteboard.

Navigation changes

In the tree panel:

Project nodes show a status indicator dot (green = active, grey = not started, amber = needs attention)
Phase nodes show a progress indicator (e.g. “3 contributions” or “approved”)
Clicking a phase node navigates to it AND highlights the relevant reference tool nodes in a subtle way (“these tools are available for this phase”)

New project from tree:

Right-clicking an institution node (or long-press on mobile) shows a context menu: + New Project
This triggers the same wizard
Creating a node of type project manually also prompts: “Would you like to use the project setup wizard?” Yes launches wizard pre-filled with the node’s title. No creates a bare node.

What does NOT change

Existing node structure — unchanged
Auth system — unchanged
Reference instance — unchanged
Tree / position / graph navigation modes — unchanged
Image maps, temporal nav, quick capture — unchanged
The standard content view (parents / this node / children) — still available for all nodes including project nodes, accessible via a small “node view” link in the project dashboard

File structure changes

/
├── api/
│   └── projects.js     (new — project creation endpoint that generates full skeleton)
├── lfti-spine.html     (modified — wizard UI, dashboard UI, navigation changes)
└── server.js           (modified — mount projects router)

The project creation logic (generating all 12+ nodes in one transaction) lives in api/projects.js rather than the frontend, so the skeleton is generated atomically server-side. The frontend sends one POST with the wizard data; the server creates all nodes and returns the project id.

POST /api/projects
  body: { name, institution_id, format, start_date, end_date, 
          workshop_dates, movements, approval_mode, group_limit,
          staff, classes, partner_institution_id }
  response: { project_id, nodes_created: n }

When you’re done

Test these five things:

Log in as ukadmin@lfti.dev. Select the UK Schools institution node. See the dominant “Start Your First Project” button. Click it. The wizard opens.
Complete the wizard with minimal input (just accept all defaults, click Next through each step). Click Launch Project. A project node appears in the tree under UK Schools with 4 movement nodes and 12 phase nodes as children.
The project dashboard loads showing the progress grid (all empty), no needs-attention items, and the participant count.
Log in as student1@lfti.dev in another browser. Navigate to the new project. Can see the project and its cycle structure. Cannot see the approval tab. Cannot delete anything.
Log in as facilitator@lfti.dev. Navigate to a phase node (e.g. Past — Gather). See a nudge toward the reference tool library for that phase (“Browse Gather tools →” linking to the reference Gather Phase node).

Reference instance seeding

2026-05-21T00:00:00.000Z

This prompt depends on the graph migration already being complete and working. Before starting, confirm that:

GET /api/nodes returns nodes with relations[] arrays
The relations_index table exists in the database
The left panel has tree / position / graph mode tabs

If any of those are not working, stop and complete the graph migration first.

What this prompt does

Seeds the LFTI reference instance — the canonical methodology layer that defines what each tool, principle, and phase means. This is not project data. It is the living documentation of the participatory methodology that LFTI uses and that partner institutions can see and learn from.

Read codeReference/PLA_TOOLS_REFERENCE.md fully before writing a single line of seed code. That document is the source of truth. Everything you build here comes from it.

Also re-read the existing seedLFTI() function in lfti-spine.html to understand the existing node structure before adding to it. You are extending the seed, not replacing it.

Structure to build

The reference instance sits as a parallel branch under the root LFTI node, connected by a contains relation. It does not replace or reorganise the existing node tree.

LFTI (root, already exists)
  ├── [existing nodes — unchanged]
  └── Reference Instance              ← new, add here
        ├── Principles & Ethos        ← methodology layer
        │     ├── [one node per principle]
        ├── Gather Phase              ← reference phase node
        │     ├── [one node per tool]
        │     │     └── [block nodes for variants/steps where specified]
        ├── Collate Phase
        │     ├── Collaborative Prioritisation  ← tool category node
        │     │     └── [tool nodes]
        │     ├── Diagramming                   ← tool category node
        │     │     └── [tool nodes]
        │     └── [remaining collate tools]
        ├── Present Phase
        │     └── [tool nodes]
        └── Cross-cutting Tools
              └── [tool nodes]

Node construction rules

Read codeReference/PLA_TOOLS_REFERENCE.md seeding instructions section (at the bottom of that document). They are authoritative. Summary:

Tool nodes:

{
  "type": "tool",
  "meta": {
    "_level": "reference",
    "_visibility": "partners",
    "phase": "gather"           // or collate / present / cross-cutting
  }
}

Principle nodes:

{
  "type": "note",
  "meta": {
    "_level": "reference",
    "_visibility": "partners",
    "category": "principle"
  }
}

Placeholder nodes (Synthesis canvas):

{
  "meta": {
    "_level": "reference",
    "_placeholder": true,
    "_placeholder_note": "Collaborative canvas deferred. Node holds shape."
  }
}

Body Map specifically:

{
  "meta": {
    "_level": "reference",
    "_facilitation_owner": "Kamoto/Mary Manzole",
    "_status": "protocol_pending",
    "_status_note": "Full facilitation protocol to be documented with Mary Manzole. Do not use without that protocol."
  }
}

Node bodies: Copy the description and key content from PLA_TOOLS_REFERENCE.md directly into node bodies. Do not summarise or paraphrase — these are reference nodes and their body text is their value. Facilitation steps go in the body as prose, not as child nodes.

Node titles: Use the ### heading text from the reference document exactly, prefixed with the phase abbreviation where helpful for disambiguation. E.g. “Gather — Transect Walk”, “Collate — Matrix Ranking”.

Relations to add

From Reference Instance node to phase nodes:

{ "type": "contains", "target": "ref_gather_phase" }
{ "type": "contains", "target": "ref_collate_phase" }
{ "type": "contains", "target": "ref_present_phase" }
{ "type": "contains", "target": "ref_principles" }

From LFTI root to Reference Instance:

{ "type": "contains", "target": "ref_instance" }

From tool nodes to existing institution nodes (provenance):

Body Map → { "type": "involves", "target": "kamoto" } (Kamoto node already exists in seed)
Pre-perceptions → { "type": "involves", "target": "glm" } (GLM node already exists)
PPP tools generally → { "type": "involves", "target": "kamoto" }

From existing cycle nodes to reference phase nodes (instance references methodology): For each of the twelve cycle nodes already in the seed (Past→Gather, Past→Collate, etc.):

{ "type": "references", "target": "ref_gather_phase" }  // or collate / present

From Pre-perceptions tool node to Whole cycle Gather node:

{ "type": "feeds", "target": "cycle_whole_gather" }

This represents that the second pre-perceptions instance runs in the Whole cycle’s Gather phase.

IDs

Use a consistent prefix scheme:

ref_ — reference instance root and phase nodes
ref_p_ — principle nodes (e.g. ref_p_handing_over_stick)
ref_g_ — gather tool nodes (e.g. ref_g_transect_walk)
ref_g_b_ — gather tool block/variant nodes
ref_c_ — collate tool nodes
ref_c_cat_ — collate tool category nodes
ref_pr_ — present tool nodes
ref_x_ — cross-cutting tool nodes

Where to add the seed code

Add a new function seedReferenceInstance() in lfti-spine.html immediately after the existing seedLFTI() function. Call it from the boot sequence after seedLFTI():

seedLFTI();
seedReferenceInstance();
loadDB();
saveDB();

seedReferenceInstance() should check if the reference instance root node already exists before seeding, to make the boot sequence safe to run multiple times:

function seedReferenceInstance() {
  if (state.nodes['ref_instance']) return; // already seeded
  // ... seed code
}

Visual treatment in the UI

Reference instance nodes already get visual treatment from the graph migration (ref badge, dimmed title, read-only styled inputs). Confirm this is working correctly for the new nodes.

In the left panel position mode, reference nodes should appear when the matching movement/phase filters are active — so when a facilitator is looking at “Gather phase” in position mode, they see both the real project’s Gather nodes AND the reference Gather tool nodes together. This is intentional: the reference is not hidden away, it is visible alongside the live work as a resource.

To enable this, reference tool nodes need meta.phase set to their phase value (already specified above). Position mode filtering should already pick this up if it filters on meta.phase — confirm this works and adjust the position mode filter logic if needed.

Expanded node set for position mode

Now that reference tools are in the system, extend the position mode context filter to include:

[ UK ] [ NZ ] [ Zambia ] [ cross-cohort ] [ reference ] [ all ]

A reference context filter shows only _level: "reference" nodes. This gives facilitators a clean way to browse the tool library while in position mode — “show me all Gather tools” by selecting phase:gather + context:reference.

What does NOT change

Existing seed nodes — unchanged
Existing API endpoints — unchanged
Existing tree view — unchanged (reference nodes appear in tree under their parent)
Temporal navigation — unchanged
Image attachments — unchanged
Footer bar — unchanged

When you’re done

Test these five things in order:

Boot the server fresh (or clear and reseed). GET /api/nodes returns reference instance nodes with correct meta._level: "reference" and relations[] arrays including involves relations to Kamoto and GLM where specified.
In the left panel tree view, navigate to the Reference Instance node. Expand it. The full hierarchy is visible: Principles & Ethos, Gather Phase, Collate Phase, Present Phase, Cross-cutting Tools, each with their child tool nodes.
Select the Body Map node. Confirm: ref badge visible, inputs styled read-only, meta._status: "protocol_pending" visible somewhere in the content section (add a small status indicator if not already present for _status meta values).
Switch to position mode. Select phase: Gather, context: reference. The Gather tool nodes appear as cards — Observation, Semi-structured Interview, Transect Walk, Body Map, Photo Walk, Story Circle, River of Life, Peer Interview, Learning Journal, Timeline, Focus Group, Pre-perceptions. No live project nodes appear.
Select phase: Gather, context: all. Both reference tool nodes AND live project Gather nodes appear together. The reference nodes have the ref badge; the live nodes do not.

Tool instance foundation

2026-05-21T00:00:00.000Z

This prompt builds the structural foundation for tool instances — the live, project-specific running version of a reference tool. Read the full codebase before starting, particularly:

The reference tool nodes and their meta fields (phase, format, location, modality etc)
The phase node structure (meta.phase, meta.movement, meta.status, meta.selected_tools)
The existing contribution/artefact flow from Phase 3
api/projects.js and the node creation patterns established there

This prompt has four distinct pieces. Build and verify each before starting the next.

PIECE 1 — Filter option extensibility

Currently tool filter properties (format, location, modality, duration, tech_level) are hardcoded strings in the tool browser UI. They need to become a database-backed extensible list so new options can be added without code changes.

New database table

CREATE TABLE IF NOT EXISTS filter_options (
  id          TEXT PRIMARY KEY,
  filter_type TEXT NOT NULL,    -- "format" | "location" | "modality" | "duration" | "tech_level"
  value       TEXT NOT NULL,    -- "indoors" | "outdoors" | "playing fields" etc
  label       TEXT NOT NULL,    -- display label, may differ from value
  created_by  TEXT,             -- user id who added it, null for seeded options
  created_at  TEXT NOT NULL,
  UNIQUE(filter_type, value)
);

Seed the initial options

const initialOptions = [
  // format
  { filter_type: 'format', value: 'individual', label: 'Individual' },
  { filter_type: 'format', value: 'group', label: 'Group' },
  // location
  { filter_type: 'location', value: 'indoors', label: 'Indoors' },
  { filter_type: 'location', value: 'outdoors', label: 'Outdoors' },
  // modality
  { filter_type: 'modality', value: 'sync', label: 'Synchronous' },
  { filter_type: 'modality', value: 'async', label: 'Asynchronous' },
  // duration
  { filter_type: 'duration', value: '<30min', label: 'Under 30 min' },
  { filter_type: 'duration', value: '30-60min', label: '30–60 min' },
  { filter_type: 'duration', value: '60min+', label: '60 min+' },
  // tech_level
  { filter_type: 'tech_level', value: 'low', label: 'Low tech' },
  { filter_type: 'tech_level', value: 'high', label: 'High tech' },
];

New API endpoints

GET /api/filter-options
  Returns all filter options grouped by filter_type
  { format: [...], location: [...], modality: [...], ... }
  Auth: any authenticated user

POST /api/filter-options
  Body: { filter_type, value, label }
  Creates a new filter option if the (filter_type, value) pair doesn't exist
  Auth: institution_admin+ only
  Returns: the created option

Frontend changes

On boot, fetch /api/filter-options and store in state.filterOptions
Replace all hardcoded filter pill arrays in the tool browser with values from state.filterOptions
In the tool browser filter UI, add a small + add filter option link at the end of each filter group (visible to institution_admin+ only). Clicking opens a tiny inline form: label input + POST /api/filter-options. On success, refreshes state.filterOptions and re-renders the filter pills.
New options are immediately available when editing any tool node’s filter meta fields

Verify piece 1

GET /api/filter-options returns all seeded options grouped correctly
Tool browser filter pills render from the API, not hardcoded
As institution_admin, add “Playing fields” to location filter type
“Playing fields” appears as a filter pill in the tool browser immediately
As student, the “+ add filter option” link is not visible

PIECE 2 — Tool instance node

When a facilitator clicks “Start this phase →” on a phase node (after selecting tools), the system currently sets meta.selected_tools on the phase node. Replace this behaviour: instead of storing selected_tools on the phase node, create a tool instance node as a child of the phase node for each selected tool.

Tool instance node structure

{
  "id": "ti_[timestamp]_[random]",
  "type": "tool_instance",
  "title": "[Tool name] — [Phase] — [Date]",
  "parent_id": "[phase_node_id]",
  "relations": [
    { "type": "references", "target": "[ref_tool_node_id]" },
    { "type": "contains",   "target": "[group_instance_id]" }
  ],
  "meta": {
    "phase": "gather",
    "movement": "past",
    "ref_tool_id": "[ref_tool_node_id]",
    "status": "preparing",
    "modality": "digital",
    "created_by": "[user_id]",
    "created_at": "ISO",
    "started_at": null,
    "completed_at": null,
    "steps": [
      {
        "id": "step_1",
        "title": "Step title",
        "body": "Step instructions",
        "order": 1,
        "capture_inline": false
      }
    ],
    "local_variations": [],
    "group_limit": 5
  }
}

Steps are copied from the reference tool node’s body at instance creation time, parsed into discrete steps. The reference tool body uses a simple convention: numbered steps separated by newlines. Parse these into the steps array. If the reference tool body has no numbered steps, create one default step: { title: "Run the activity", body: "[full tool body text]", order: 1 }.

local_variations is an empty array at creation. When a facilitator edits a step (title or body) before Start is pressed, record the original and changed values here:

{ "step_id": "step_1", "field": "body", "original": "...", "modified": "...", "modified_at": "ISO" }

This is the variation tracking mechanism for F17.

On creation:

Copy meta.phase and meta.movement from the parent phase node
Copy meta.group_limit from the project node (walk up parent chain to find it)
Fetch reference tool node to get steps and filter meta
Set status to “preparing”
Update parent phase node: remove meta.selected_tools (no longer needed), set meta.status = “active”

New API endpoint

POST /api/tool-instances
  Body: { phase_node_id, ref_tool_ids: ["id1", "id2"] }
  Creates one tool_instance node per ref_tool_id as child of phase_node_id
  Returns: { tool_instance_ids: ["ti_...", "ti_..."] }
  Auth: facilitator+

Call this endpoint from the “Start this phase →” button instead of the current meta.selected_tools approach.

Verify piece 2

Select two tools on Past — Gather phase node, click “Start this phase →”
Two tool_instance nodes appear as children of Past — Gather in the tree
Each tool_instance node has correct meta: phase, movement, ref_tool_id, status: preparing
Each has steps array populated from the reference tool body
relations[] contains a references relation pointing to the correct ref tool node
Phase node meta.status is now “active”, meta.selected_tools is gone

PIECE 3 — Group instance nodes

When a tool instance is created, generate a default set of group instance nodes as children. The number of groups comes from the class node’s meta.suggested_groups (set during project wizard). If no class is associated or suggested_groups is not set, default to 3 groups.

Group instance node structure

{
  "id": "gi_[timestamp]_[random]",
  "type": "group_instance",
  "title": "Group [n]",
  "parent_id": "[tool_instance_id]",
  "relations": [
    { "type": "involves", "target": "[tool_instance_id]" }
  ],
  "meta": {
    "tool_instance_id": "[tool_instance_id]",
    "group_number": 1,
    "modality": "digital",
    "status": "not_started",
    "members": [
      {
        "name": "",
        "role": "",
        "person_node_id": null
      }
    ],
    "step_trace": [],
    "submitted_at": null,
    "uploaded_by": null,
    "on_behalf_of": null
  }
}

members array: starts empty (or with blank slots matching the reference tool’s suggested group size if that field exists on the ref tool node meta). Each member slot has name (free text), role (free text), and optionally a person_node_id if matched to a roster entry.

step_trace records timestamps as the group progresses through steps:

[
  { "step_id": "step_1", "entered_at": "ISO", "exited_at": "ISO" },
  { "step_id": "step_2", "entered_at": "ISO", "exited_at": null }
]

This is the activity trace for the facilitator view (F17 basis).

modality defaults to “digital”. Can be changed to “paper” by the facilitator in the tool instance view before Start is pressed.

on_behalf_of / uploaded_by: for proxy uploads (F16) — when a facilitator uploads content for a paper group, set uploaded_by to the facilitator’s user id and on_behalf_of to the group_instance_id.

Generate group instances

Add group instance creation to POST /api/tool-instances: After creating the tool_instance node, create N group_instance child nodes. N = class.meta.suggested_groups or 3 if not available. Return group_instance_ids in the response.

Verify piece 3

After “Start this phase →”, expand a tool_instance node in the tree
See N group_instance child nodes (matching suggested_groups or 3 default)
Each group_instance has correct meta: tool_instance_id, group_number, modality: digital, status: not_started, empty members array

PIECE 4 — Tool instance view and group management

When a node of type tool_instance is selected, render a dedicated view instead of the standard parents/content/children layout. This is the facilitator’s control panel for this tool session.

Tool instance view layout

┌─────────────────────────────────────────────────────────────────┐
│ [Tool name]                    [● Preparing]  [node view ↗]    │
│ [Phase] · [Movement] · [Date created]                           │
│ Reference: [ref tool name →] (clickable, navigates to ref node) │
├─────────────────────────────────────────────────────────────────┤
│ TABS: [ Setup ] [ Groups n ] [ Contributions n ] [ Summary ]    │
├─────────────────────────────────────────────────────────────────┤
│ [tab content]                                                    │
└─────────────────────────────────────────────────────────────────┘

Status badges:

preparing → amber · “Preparing”
active → accent · “Active”
complete → muted blue · “Complete”

Setup tab

Shows the tool steps, editable before Start is pressed. Read-only after.

STEPS  (editable until started)

  1. [Step title — editable input]
     [Step body — editable textarea]
     [capture inline: ○ yes ● no]
     [↑ move up] [↓ move down] [+ insert after] [× remove]

  2. ...

  [+ Add step]

──────────────────────────────────────────────
RESOURCES
  Format: group · Indoors · Synchronous · 60min+ · Low tech
  (rendered from ref tool meta filter values — read only here)

──────────────────────────────────────────────
[ Start tool → ]   (disabled until at least one group has ≥1 named member)

When a step is edited (title or body changed from the original):

Record the variation in meta.local_variations
Show a small “modified” indicator next to that step
A “reset to original” link restores the reference text

“Start tool →” button:

Sets tool_instance meta.status = “active”, meta.started_at = now
Saves via PUT /api/nodes/:id
Switches to Groups tab
Steps become read-only

Groups tab

A grid of group cards — one per group_instance child node.

GROUPS  3                                    [+ Add group]

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ GROUP 1         │  │ GROUP 2         │  │ GROUP 3  📄     │
│ ● digital       │  │ ● digital       │  │ ○ paper         │
│                 │  │                 │  │                 │
│ Tom P    mapper │  │ [empty]         │  │ [empty]         │
│ Sarah K  noter  │  │                 │  │                 │
│ Amara D  walker │  │                 │  │                 │
│                 │  │                 │  │                 │
│ not started     │  │ not started     │  │ not started     │
│ [Edit]          │  │ [Edit]          │  │ [Upload] [Edit] │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Group card states:

not_started → dim border
in_progress → accent border, step progress indicator
submitted → green border, “✓ submitted”
paper_pending → amber border, “📄 awaiting upload”

Modality toggle: Each card has a small toggle: ● digital / ○ paper. Switching to paper shows “📄” badge and adds Upload button. Available before and during the session (groups can switch if device fails).

Edit group (inline panel below the card):

Opens inline when Edit is clicked:

Group 1  ● digital  ○ paper

Members:
  Name: [Tom P      ]  Role: [mapper  ]  [×]
  Name: [Sarah K    ]  Role: [noter   ]  [×]
  Name: [Amara D    ]  Role: [walker  ]  [×]
  Name: [           ]  Role: [        ]  [+ add member]

Roles suggested by this tool: mapper, noter, walker, interviewer
(pulled from ref tool node meta.suggested_roles if it exists)
[Save]  [Cancel]

Names and roles are free text. No validation — blanks acceptable, duplicates acceptable. Save writes to group_instance meta.members via PUT /api/nodes/:id.

Upload button (paper groups):

Opens the image upload flow (existing image attachment feature) pre-configured for this group instance. On upload completion:

Sets group_instance meta.uploaded_by = current user id
Sets group_instance meta.on_behalf_of = group_instance_id
Sets group_instance meta.status = “submitted”
Creates a contribution node as child of the group_instance

+ Add group button: Creates a new group_instance node as child of this tool_instance. Auto-numbers (Group 4, Group 5 etc).

Contributions tab

All contribution nodes across all group instances for this tool, displayed as cards.

CONTRIBUTIONS  7                    Filter: [ All ] [ Group 1 ] [ Group 2 ] ...

[contribution card — group name, timestamp, approval status, content preview]
[contribution card]
...

[ + Add contribution ]   (facilitator can add directly — proxy for paper groups)

Matches the contributions area from Phase 3 but scoped to this tool instance. Group filter tabs pull group names from group_instance nodes.

“+ Add contribution” opens quick-capture pre-filled:

type: artefact
parent: the group_instance_id (not the tool_instance directly)
meta.tool_instance_id, meta.phase, meta.movement inherited
meta.approval_status: pending
meta.uploaded_by: current user (for proxy tracking)

Summary tab

Read-only. Available at all times but most useful after completion.

SUMMARY

Status: Active · Started: [datetime]

GROUPS
  Group 1  ●  Tom P · Sarah K · Amara D     submitted  3 contributions
  Group 2  ●  [unnamed]                      in progress  step 2/5
  Group 3  📄  [unnamed]                     paper pending  0 uploaded

ACTIVITY TRACE  (Group 2)
  Step 1   entered 10:23  exited 10:31   (8 min)
  Step 2   entered 10:31  in progress

  ⚠ Group 3 has not submitted. Paper groups need facilitator upload.
  ⚠ Group 2 has been on step 2 for 12 minutes.

CONTRIBUTIONS  7 total · 5 pending approval · 2 approved

The ⚠ warnings are the facilitator’s nudge system:

Paper group not yet uploaded → always show if session is active
Group on same step for > 10 minutes → show (time threshold configurable in tool_instance meta, default 10 min)
Group submitted with 0 contributions → show

These are computed client-side from step_trace timestamps and contribution counts — no new endpoint needed.

What does NOT change

Standard node view — unchanged, accessible via “node view ↗” link
Reference tool nodes — unchanged (read from, not written to, by instances)
Project dashboard — unchanged (progress grid already reads contribution counts)
Auth system — unchanged
Image map feature — unchanged (used by Upload button for paper groups)
Quick capture overlay — unchanged (used as base for contribution capture)
Tree navigation — unchanged (tool_instance and group_instance nodes appear in tree as children of phase nodes and tool_instances respectively)

File changes

db/database.js          — filter_options table + seed
api/filter-options.js   — GET and POST endpoints
api/tool-instances.js   — POST endpoint (creates instance + group instances)
api/projects.js         — add /api/projects/:id/progress update for tool instances
server.js               — mount new routers
lfti-spine.html         — tool instance view, group management, 
                          filter pill extensibility, boot fetches filter options

When you’re done — test in order

Piece 1: As institution_admin, add “Playing fields” as a new location filter option via the tool browser. It appears as a filter pill immediately. As student, the add link is not visible.
Piece 2: Select Body Map and Story Circle on Past — Gather. Click “Start this phase →”. Two tool_instance nodes appear in the tree as children of Past — Gather. Each has steps parsed from the reference tool body and a references relation to the correct ref tool node.
Piece 3: Expand a tool_instance node. See 3 group_instance child nodes (or matching suggested_groups count). Each has modality: digital, status: not_started.
Piece 4 — Setup tab: Click a tool_instance node. See the dashboard view with Setup tab active. Steps are editable. Edit one step body — see “modified” indicator and variation recorded in meta.local_variations. Click “reset to original” — step body restored.
Piece 4 — Groups tab: Switch to Groups tab. See 3 group cards. Edit Group 1 — add 3 member names and roles, save. Toggle Group 3 to paper — Upload button appears. Click “+ Add group” — Group 4 appears.
Piece 4 — Start: Click “Start tool →” (after adding at least one named member). Status changes to Active. Setup tab steps become read-only. Summary tab shows Group 1 with members listed.
Piece 4 — Contributions: Switch to Contributions tab. Click “+ Add contribution”. Quick-capture opens. Save a test contribution. It appears in the contributions tab with “pending” badge and the correct group name. Summary tab shows updated contribution count and ⚠ for groups with 0 contributions.