docs(wiki): 3-D known issues and what to diff after the 3-D fixes (SP6 1/3)

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **Wiki: 3-D known issues and what to diff after the 3-D fixes.** *Known issues* gains a 3-D section (one camera pair and no optics correction, flagged fused depth, GL-1 vs GL-16 frames, the shared native water column, `flip`), and *Reanalysing after a metric fix* lists the 3-D numbers that changed since v0.1.0.
 - **User guide: the 3-D data path after the review fixes.** The guide describes the Fusion dialog's upside-down box and helper line, the depth provenance flags, `z_cm`, the water column's effect on IL-16/IL-17, the README count of samples outside it, and GL-16's `frac_frames_used_3d`; the PDF is rebuilt. The guide has no screenshot of the Fusion dialog or the native Calibration page, so none changed.
 - **Clearer wording where the 3-D settings are made.** The Fusion dialog says under the shared horizontal axis and flip that they are used only to check that the two views agree and do not change the fused positions (the two never moved the fused data, but sat beside the surface and floor rows as if they did). The Calibration page's water-column help says one surface and floor apply to every session, so the files must share a vertical axis and an origin (the origin cannot be checked from the files), and that samples outside the column are left out of the vertical-position metrics and of the 3-D path length and speed. The run `README.md` of a native 3-D session with a water column gains a row, **Samples outside the water column**, with the count (0 when nothing is outside), so the exclusion is visible next to the numbers it affects.
 - **Fusion accepts an upside-down side view.** `FusionSettings` required the water surface to be the smaller image row, so a side camera mounted upside down (or seen through a mirror) could not be set up, while the native water column accepted either order. Either order is now valid and only equal rows are refused; the depth counts from the surface row as entered, and the side view's horizontal scale no longer changes sign for an inverted pair. The Fusion dialog keeps its two lines upright and gains a **The side view is upside down** box that swaps which line is the surface and relabels the lines, the rows and the dialog's check message accordingly. Existing projects are unchanged.

docs/wiki/Known-Issues.md

@@ -1,6 +1,6 @@
 # Known issues
 
-**Last reviewed:** 2026-10-08, against v0.1.0 and `main`.
+**Last reviewed:** 2026-10-11, against v0.1.0 and `main` (1c9e828).
 
 What is currently wrong, missing, or in flux. Fixed items are removed from this page and
 live in the
@@ -84,6 +84,35 @@ video pixels, and should be redrawn.
 needs — frame rate is the common case — you get `READER_OPTION_MISSING` and must supply it.
 A guessed frame rate would corrupt every speed and path-length value instead.
 
+## 3-D data
+
+**3-D assumes one right-angle camera pair and no optics correction.** A fused project
+combines a top and a side view as if both were orthographic: the side view's horizontal
+scale comes from the tank height (square pixels, no perspective), there is no refraction or
+parallax correction, and its vertical axis is image y, so a rotated side camera cannot be
+described. A wrong tank height scales every vertical distance. A side camera mounted upside
+down is supported (tick **The side view is upside down** in the Fusion dialog).
+
+**A fused depth is kept, and flagged, when it rests on a reconstructed side position.** Where
+the side view was gap-filled or jump-replaced, `depth_interpolated` or `depth_jump_replaced`
+is True in the per-frame table; the depth itself is not blanked. Report how much of a 3-D
+result rests on flagged frames. Native 3-D files are cleaned like x and y: `z` is gap-filled
+and smoothed with the same settings, so the smoothing window changes IL-16 and IL-17.
+
+**GL-1 and GL-16 can use different frames.** Both skip a frame when an animal is missing, but
+GL-16 also needs a depth for every animal, so missing depth leaves it on fewer, cleaner
+frames and biases `mean_nnd_3d_cm` upward against `mean_nnd_cm`. Read `frac_frames_used_3d`
+before comparing the two.
+
+**The native water column is one surface and floor for the whole project.** Native files in
+a project must share a vertical axis (a mix is refused at import) and an origin (this cannot
+be checked from the files, so check it yourself). Samples outside the column are left out of
+IL-15, IL-16, IL-17 and GL-16, never clipped, and the run `README.md` counts them.
+
+**`flip` reverses the vertical axis only, which also mirrors the view from above.** For a
+native file, headings and the sign of `left_right_turn_bias` change with it. The horizontal
+plane itself is right-handed for every `vertical_axis`.
+
 ## Output and performance
 
 **Excel splits large tables across sheets.** Past Excel's row limit, the per-frame table

docs/wiki/Reanalysing-After-a-Metric-Fix.md

@@ -39,6 +39,14 @@ zone metrics emitted per-slot rows on identity-free sessions, and Z-1, Z-2 and Z
 pooled without `individual_id` while Z-3 … Z-9 require identity (D-016); per-animal
 metadata is now matched per animal instead of being copied onto every animal (D-025); distance (IL-1) and freezing bouts (IL-7) are NaN, not 0, for an animal that was never measured (D-034); zone events (Z-5) report the original video frame and time, as the per-frame table does, and Z-6 states its origin frame (D-032); and a session tracked in separate intervals is processed on real elapsed time, so values near the junctions between its intervals change (D-035).
 
+3-D projects changed in several places after v0.1.0, so diff these first: native-file
+IL-16, IL-17 and `max_speed_3d_cm_s` (the vertical coordinate is now gap-filled and smoothed
+like x and y, so these fall); native IL-15, IL-16, IL-17 and GL-16 when a water column is set
+(samples outside it are now left out); IL-15 `frac_outside_extent` on fused projects with
+top-view gaps (its denominator is now the side-view samples); IL-11 `mean_heading_rad` and
+`left_right_turn_bias` for native files read with a vertical axis of `x` or `y` (the
+horizontal plane is now right-handed). GL-16 also gains `frac_frames_used_3d`, a new column.
+
 Metric-level detail lives in
 [`docs/METRICS_SPEC.md`](https://github.com/mbel-tech/Track2Data/blob/main/docs/METRICS_SPEC.md),
 and the reasoning behind a change in