Restructure the documents around the work, not around FEM

TASKS.md was scoped to preparing for the FEM work, because that is what it was
asked for, but the foundation is upstream of FEM rather than downstream: FEM is
an application of studio, and integration built on a foundation that is about to
move is rework. So the tracks invert. Foundation is primary, magpylib core runs
in parallel because its lead time is upstream review rather than ours, and
validation follows except for the physics layer, which is orthogonal -- a
different repo, magpylib objects only, no solver and no open decision.

The two foundation items were buried. Killing the round trip sat under "drag
reduction" as though it were tidying, when it is the whole of the diagnosis;
parameterised instancing sat in "not started" despite being the missing reuse
feature and the answer to all four units of reuse.

Instancing now has a design document rather than a line in a list, because it is
the highest-design-risk item and the most tempting to start coding. The prior
art settles the two questions that looked hardest: Godot, Onshape and Jsonnet
all put a definition in its own file, and Godot's recurring instance-value bugs
come from allowing arbitrary overrides, so an instance supplies declared
arguments and nothing else. The useful observation is that the parameter
declaration already exists -- variables plus variable_bounds are a signature in
everything but name, so instancing is mostly letting another document supply
them. Six questions stay open, version pinning and whether a document's
variables really are its public signature being the ones that would hurt to get
wrong.

Layout follows the same idea: root holds the front door, the state and the work,
docs/ holds the long-form thinking, and both README and TASKS carry a map so
neither a person nor an agent has to guess which file answers which question.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Alexboiboi

README.md

@@ -237,7 +237,18 @@ fails at first contact, before anyone sees a feature — and it is what lets
 `.vsix` attached to each release is the same build, for anyone who would rather
 install it by hand.
 
-See [CONTINUE.md](CONTINUE.md) for the current state and what is next.
+## Project documents
+
+| Question                    | Document                                 |
+| --------------------------- | ---------------------------------------- |
+| What is built?              | [CONTINUE.md](CONTINUE.md)               |
+| What is next?               | [TASKS.md](TASKS.md)                     |
+| Why is it going that way?   | [docs/direction.md](docs/direction.md)   |
+| How does instancing work?   | [docs/instancing.md](docs/instancing.md) |
+| How does FEM validation go? | [docs/fem.md](docs/fem.md)               |
+
+The three at the root are the state, the work and the front door; `docs/` holds
+the long-form thinking behind them.
 
 ## License
 

TASKS.md

@@ -1,201 +1,158 @@
-# Tasks — preparing for the FEM work
-
-The executable breakdown sitting between `FEM.md` (the plan) and doing it.
-`DIRECTION.md` holds the architectural position; the review that produced this
-list found the two do not collide.
-
-## The review finding that matters
-
-The direction research landed on **keep the document as the artifact**, and
-`FEM.md` §12.1 already assumes exactly that: a cache key over source-affecting
-events, `sources_all` / `sensors_all` as the partition, `set_rollback` and
-`undo` as free FEM navigation. Had the answer been code-as-truth, all of §12.1
-would need rewriting to a trace hash. It does not.
-
-**So the open direction question blocks nothing below.** One positive
-interaction rather than a dependency: parameterised instancing would give FEM a
-library of validated assemblies and sweeps over instance parameters.
-
-## Ordering
-
-- **C starts now** — no blockers at all; needs no solver and no studio change.
-- **B starts now, in parallel** — the longest lead, and it is upstream review
-  time rather than ours.
-- **A1 and A2 before any studio-side FEM UI.** A2's cost rises the longer it
-  waits.
-- **D is independent**, and shrinks the maintenance surface before FEM adds to
-  it.
+# Tasks
+
+What to do next, ordered by what gates what. The reasoning behind each item
+lives in the plan it came from — this file stays thin enough to work from.
+
+| Question                    | Document                                 |
+| --------------------------- | ---------------------------------------- |
+| What is this?               | [README.md](README.md)                   |
+| What is built?              | [CONTINUE.md](CONTINUE.md)               |
+| **What do I do next?**      | **this file**                            |
+| Why is it going that way?   | [docs/direction.md](docs/direction.md)   |
+| How does instancing work?   | [docs/instancing.md](docs/instancing.md) |
+| How does FEM validation go? | [docs/fem.md](docs/fem.md)               |
+
+**Track F (foundation) is primary.** It is what studio _is_ under the
+positioning in `docs/direction.md` §1, and everything else is an application of
+it. M runs in parallel because its lead time is upstream review rather than
+ours. V is downstream of F except for V1, which is orthogonal — a different repo
+that touches none of this.
 
 ---
 
-## Group A — studio work the FEM plan needs
-
-### A1 — Jobs in the RPC protocol
+## Track F — Foundation
 
-**What.** Worker subprocess, server-initiated notifications, a job id space,
-cancellation.
+### F1 — Kill the round trip
 
-**Why.** `serve()` is a strictly serial blocking loop: one line in, one line
-out, in order; every write echoes a request `id`, so there are no
-server-initiated messages; and there is no `threading`, `asyncio` or
-`subprocess` anywhere in the engine. A solve through it freezes the scene tree,
-the inspector, the sliders and the 3D view for minutes. It also pays for
-something already wanted — mesh reorientation blocks the same loop at 16 s for
-20k faces.
-
-**Done when.** A long call runs without blocking any other request, reports
-progress, and can be cancelled; the existing test suite still passes.
+**What.** `parse_script` goes, with the matched emitter/parser idiom pairs
+(`_mirror`, `_superquadric`, the `for i in range(1, n)` loop shape, the
+`_name_copy` line emitted and then skipped). `to_script` becomes export and
+recording only.
 
-**Blocks.** `FEM.md` M7, and all three workflows in §12.
+**Why.** `docs/direction.md` §2 and §5.1. Every project in its §4 table
+generates one-way. This is a deletion with a known shape and it shrinks the
+surface F2 has to work in.
 
-### A2 — Refusal-first job API
+**The decision inside it.** The script tab stops being applied on save. That is
+a UI change, not only a deletion, and it should be decided rather than
+discovered. `load_script` and `apply_script` keep working by execution, which is
+already their fallback.
 
-**What.** The job API **errors**, rather than warns, on: a residual without
-convergence metadata, a solve past budget, and a comparison mixing `ideal` and
-`physical` mode.
+**Done when.** The round trip is gone, import still works by execution, and the
+two-tier cliff is unreachable.
 
-**Why.** §13.5. A human glances at a "provisional" badge; an agent ignores a
-warning field and hill-climbs on mesh noise, confidently, for hours. And the
-guardrail cannot live in a skill file — the README's _"there is no second
-validation layer"_ settles where it goes. Cheap now, expensive once callers
-depend on permissive behaviour.
+### F2 — Parameterised instancing
 
-**Done when.** Each of the three refusals has a test asserting an error rather
-than a warning.
+**What.** A definition document with declared parameters, and an `instance`
+event that references it with arguments. Design in
+[docs/instancing.md](docs/instancing.md).
 
-### A3 — Source/probe hash partition
+**Why.** The missing reuse feature. All four wanted units of reuse are
+composition units, and a structured format composes if it has instancing plus
+exported parameters.
 
-**What.** A content hash over field-affecting events only — magnets, currents,
-anything with μr ≠ 1, and the transforms carrying them — excluding sensors and
-pixel grids.
+**Design first.** Six open questions in `docs/instancing.md` §5 — version
+pinning, nested instances, composition with patterns, editing through an
+instance, whether a document's variables are its signature, and whether
+same-document definitions are worth having. This is the highest-design-risk item
+in the plan and the most tempting to start coding.
 
-**Why.** Solve once, probe forever. Moving a sensor must not invalidate a solve.
+**Done when.** Design questions closed, then: an instance resolves in `_build`,
+`to_script` emits a call, a definition round-trips by hash, and a pattern of
+instances works.
 
-**Done when.** Moving a sensor leaves the hash unchanged; changing a magnet
-changes it; and undoing back to a previous state reproduces that state's earlier
-hash exactly. The last property is what turns history navigation into free FEM
-navigation.
+### F3 — GUI as parameter binder
 
-### A4 — Units
+**What.** Introspect a definition's parameters, render widgets, rebuild, draw.
 
-**What.** A unit _kind_ on a variable, beside `integer`; one model unit per
-document; emitters convert at the boundary; the UI formats.
+**Depends on** F2 — there are no parameters to bind until definitions exist.
 
-**Why.** AEDT wants `"5mm"`, solvers want consistent SI, and `FEM.md` §6 chose
-metadata over unit-carrying values so no document migrates. Cheaper than that
-section implies: `_PARAM_UNITS` already sits beside `_PARAM_ATTRS`.
+**Why.** `docs/direction.md` §5.3. The sync surface shrinks to "parameters →
+widgets", which cannot drift. Proven shape: OpenSCAD Customizer, Storybook
+controls, Streamlit.
 
-**Done when.** Every existing document loads unchanged and the script round-trip
-is stable.
+### F4 — Grow `expressions.py` toward Starlark
 
-**Blocks.** M6.
+**Deliberately not scheduled.** `docs/direction.md` §5.4 — the right answer and
+the expensive one. Starlark took Google eight years. Nothing forces the choice
+yet.
 
 ---
 
-## Group B — magpylib core (start now; upstream lead time is the constraint)
+## Track M — magpylib core (start now; the constraint is upstream review)
 
-### B1 — `susceptibility` / μr as a documented property
+### M1 — `susceptibility` / μr as a documented property
 
-**What.** A real property on magnets, rather than the attribute
-`magpylib-material-response` monkey-attaches and searches parents for.
-
-**Why.** It is the `physical`-mode input. Without a shared convention the
-exporter invents its own home for μr and it differs from material-response's —
-at which point tier 1's three-way comparison silently compares magnets that are
-**not the same magnet**, and the discrepancy looks like physics.
+**Why.** It is the `physical`-mode input (`docs/fem.md` §3.2). Without a shared
+convention the exporter invents its own home for μr and it differs from
+`magpylib-material-response`'s — at which point tier 1's three-way comparison
+silently compares magnets that are **not the same magnet**, and the discrepancy
+looks like physics.
 
 **Done when.** Merged upstream, or a documented studio-side convention exists
 that material-response also reads.
 
-### B2 — Public constructor-parameter introspection
-
-**What.** One accessor upstream replacing studio's hardcoded `_PARAM_ATTRS`.
+### M2 — Public constructor-parameter introspection
 
-**Why.** The physics layer needs the identical table, so a new magnet class in
-core would fall silently through **both** copies.
+**Why.** Studio hardcodes `_PARAM_ATTRS`; the physics layer (V1) needs the
+identical table, so a new magnet class in core would fall silently through
+**both** copies.
 
 **Done when.** `get_params` reads it instead of the literal tuple.
 
 ---
 
-## Group C — the physics layer (unblocked, start today)
-
-### C1 — Package skeleton and the home decision
+## Track V — Validation
 
-**What.** Settle `FEM.md` §4's split — physics on magpylib objects in a
-standalone package, parametrics on the document in studio — and create it.
+Full plan and its gates in [docs/fem.md](docs/fem.md). Only V1 is orthogonal to
+Track F; the rest build on the foundation and should follow it.
 
-**Done when.** It imports, has CI, and depends only on magpylib.
+### V1 — The physics layer (orthogonal — start any time)
 
-### C2 — Conventions module
+Package skeleton and the §4 home decision · conventions module (§3.1's verified
+table, including the two off-by-two traps) · the required `ideal`/`physical`
+mode switch (§3.2) · solver-free conformance: the `getJ` occupancy test plus the
+volume/centroid check.
 
-**What.** Pose → euler, J → (Hc, μr, world direction), geometry-parameter
-normalisation. Pure functions, no solver, no vendor, no document.
+**Why it can run alongside F.** Different repo, magpylib objects only, no
+solver, no studio change, no open decision. Reaches `docs/fem.md`'s **G1** with
+nothing installed.
 
-**Why.** `FEM.md` §3.1's table, verified against a live checkout — including the
-two off-by-two traps: `Cylinder` and `Sphere` take **diameter**, and `Cuboid`
-takes **full** edge lengths while `create_box` takes a corner.
+### V2 — Units
 
-**Done when.** Every row of that table is pinned by a test.
+Unit _kind_ on a variable beside `integer`; one model unit per document;
+emitters convert at the boundary. Cheaper than `docs/fem.md` §6 implies —
+`_PARAM_UNITS` already sits beside `_PARAM_ATTRS`. **Interacts with F2**: a
+definition's parameters want units for the same reason its variables do.
 
-### C3 — The ideal / physical switch
+### V3 — Jobs in the RPC protocol
 
-**What.** A required mode argument with no default.
+Worker subprocess, server-initiated notifications, a job id space, cancellation.
+`serve()` is a strictly serial blocking loop with no threading, asyncio or
+subprocess anywhere in the engine, so a solve through it freezes the whole UI
+for minutes. Also pays for mesh reorientation blocking the same loop at 16 s.
 
-**Why.** §3.2. A μr = 1 magnet and a μr = 1.05 magnet with the same Br are
-different magnets. `ideal` validates our translation; `physical` measures the
-modelling error. Conflating them yields a comparison that means nothing while
-looking rigorous.
+### V4 — Refusal-first job API
 
-**Done when.** No call site can omit it.
+Errors, not warnings, on: a residual without convergence metadata, a solve past
+budget, a comparison mixing `ideal` and `physical`. `docs/fem.md` §13.5 — an
+agent ignores a warning field and hill-climbs on mesh noise. **Cost rises the
+longer callers depend on permissive behaviour**, so decide the shape early even
+if the work lands late.
 
-### C4 — Solver-free conformance tests
+### V5 — Source/probe hash partition
 
-**What.** The `getJ` occupancy test, plus the volume/centroid check beside it.
-
-**Why.** Catches centre-vs-corner, diameter-vs-radius, degrees-vs-radians,
-local-vs-world polarisation and a wrong Euler convention — with **nothing
-installed**.
-
-**Done when.** Green for `Cuboid`, `Cylinder`, `Sphere` and `CylinderSegment`
-against a pure-Python membership evaluator. This is `FEM.md`'s **G1**.
+A content hash over field-affecting events only, excluding sensors and pixel
+grids. Solve once, probe forever. Undo back to a previous state must reproduce
+that state's earlier hash — that property is what turns history navigation into
+free FEM navigation.
 
 ---
 
-## Group D — drag reduction
-
-### D1 — Kill `parse_script`; `to_script` becomes export only
-
-**What.** Remove the read-back path and the matched emitter/parser idiom pairs
-(`_mirror`, `_superquadric`, the `for i in range(1, n)` loop shape, the
-`_name_copy` line that is emitted and then skipped).
-
-**Why.** `DIRECTION.md` §2's cliff and §5.1, and every project in its §4 table
-generating one-way. Shrink the maintenance surface before FEM adds to it.
-
-**Careful.** `load_script`, `apply_script` and the script tab depend on it. The
-script tab stops being applied on save — that is a UI change, not only a
-deletion, and it needs deciding rather than discovering.
-
-**Done when.** The round trip is gone, import still works by execution, and the
-two-tier cliff is no longer reachable.
-
-### D2 — ~~Rewrite `DIRECTION.md`~~ **done**
-
-Rewritten around _data is the artifact / one-way generation / parameterised
-instancing_, with code-as-truth kept as §7's recorded-and-rejected alternative
-and §4 carrying the Bazel, Jsonnet, Onshape, Godot and OpenSCAD evidence.
-
----
+## Not scheduled, and why
 
-## Not started, and why
-
-- **Anything downstream of `FEM.md`'s G3 spike** — the solver is deliberately
-  undecided until it is measured.
-- **Parameterised instancing** (`DIRECTION.md` §5.2) — the missing reuse
-  feature, and the answer to all four units of reuse. Agreed in principle, not
-  scoped, and not a FEM dependency, so it is deliberately not in the groups
-  above.
-- **Growing `expressions.py` toward Starlark** (`DIRECTION.md` §5.4) — the right
-  answer and the expensive one. Nothing forces the choice yet.
-- **The agent skill (M9)** — a skill may only describe an API that exists.
+- **Anything downstream of `docs/fem.md`'s G3 spike** — the solver is
+  deliberately undecided until it is measured.
+- **F4** — see above.
+- **The agent skill** (`docs/fem.md` M9) — a skill may only describe an API that
+  exists.

DIRECTION.md docs/direction.mdDIRECTION.md renamed to docs/direction.md

@@ -4,7 +4,8 @@
 from the evidence in §4 and is not implemented. §7 records the alternative that
 was argued first and rejected — kept because the reasoning is worth having, and
 because it is how this file's conclusion arrived. Companion to `CONTINUE.md`
-(what is built), `FEM.md` (where validation goes) and `TASKS.md` (what to do).
+(what is built), `docs/fem.md` (where validation goes) and `TASKS.md` (what to
+do).
 
 ---
 
@@ -60,7 +61,7 @@ already visible:
   forever.
 
 And the failure is not graceful.
-[`importer.py:861`](magpylib_studio/importer.py):
+[`importer.py:861`](../magpylib_studio/importer.py):
 
 > _"A script in the shape `to_script` emits -> (document, None), or (None,
 > reason) when it is anything else and **has to be executed**."_
@@ -353,11 +354,11 @@ added.
 | `to_script`, as export and recording   | the matched emitter/parser pairs |
 | field, figures, field maps, sweeps     | the two-tier cliff               |
 | `expressions.py` — and §5.4 grows it   | the script tab applying on save  |
-| the whole of `FEM.md`                  |                                  |
+| the whole of `docs/fem.md`             |                                  |
 
-`FEM.md` is unaffected in particular: §12.1 already assumes the document stays
-the artifact, keys its cache on source-affecting events, and treats `undo` and
-`set_rollback` as free navigation over the same fold.
+`docs/fem.md` is unaffected in particular: §12.1 already assumes the document
+stays the artifact, keys its cache on source-affecting events, and treats `undo`
+and `set_rollback` as free navigation over the same fold.
 
 ---
 

FEM.md docs/fem.mdFEM.md renamed to docs/fem.md

@@ -785,12 +785,12 @@ and runs an analysis unattended. It is a good fit, with two hard constraints.
 
 ### 13.1 This document is not that file, and must not become it
 
-`FEM.md` is a **plan**: it argues, records the alternatives it rejected, carries
-open questions, and above all **describes a system that does not exist yet**.
-Hand it to an autonomous agent today and the agent will call `validate()` and
-`read_result()` in good faith, with a citation. Plausible hallucination backed
-by an authoritative-looking document is the worst failure mode an agent artifact
-has.
+`docs/fem.md` is a **plan**: it argues, records the alternatives it rejected,
+carries open questions, and above all **describes a system that does not exist
+yet**. Hand it to an autonomous agent today and the agent will call `validate()`
+and `read_result()` in good faith, with a citation. Plausible hallucination
+backed by an authoritative-looking document is the worst failure mode an agent
+artifact has.
 
 A skill is the opposite artifact: imperative, present tense, current state only,
 no history and no roads not taken. Two files, the skill derived from the plan,