@protoboardai/ext-docs 0.0.0-stage → 0.2.1

package/skills/uhd-tech-docs/references/test-data.md

@@ -0,0 +1,49 @@
+# Test data
+
+## Convention
+
+```
+docs/test-data/<test-id>.json               one file per test; id == file name
+```
+
+Schema: [`../templates/test-data.schema.json`](../templates/test-data.schema.json).
+Example of a measured file: [`../templates/test-data.example.json`](../templates/test-data.example.json).
+
+| Field | Meaning |
+| --- | --- |
+| `id`, `title` | stable test id (used by documents), human title |
+| `status` | `"standin"` (derived from the model, watermarked) or `"measured"` |
+| `subject` | `{ system, modules[] }` — what was tested |
+| `conditions[]` | `{ name, value, unit }` — supply voltage, ambient, propeller, firmware… (`unit: ""` for text) |
+| `provenance` | `method` (always); stand-in: `derivedFrom[]` (value queries), `assumptions[]`, `generator`, `generatedAt`; measured: `date`, `operator` and/or `instruments[]`, `rawFiles[]` |
+| `columns[]` | `{ id, label, unit }` |
+| `rows[][]` | one value per column |
+| `summary[]` | `{ id, label, value, unit }` — headline figures documents quote |
+
+## Stand-in data
+
+`protoboard run tech-docs` (input `standins`, default true) first writes the recipe named in
+`docspec.testData.standins` (e.g. `multirotor`, the extension's `lib/standins/multirotor.ts`). A recipe derives
+plausible data from model values, lists each input query in `provenance.derivedFrom`, and states
+every value the model could not supply in `provenance.assumptions`. Documents draw stand-in data
+with the **STAND-IN DATA — NOT MEASURED** watermark, an in-chart badge, a `stand-in` tag on the
+chart title and the **S** marker on every value.
+
+Quadcopter stand-ins (from the MEPS motor's 50 %/100 % thrust points, battery V/capacity, masses,
+O4/GNSS supply figures): `throttle-sweep`, `hover-current`, `flight-time`, `thrust-to-weight`,
+`esc-temp-punchout`, `battery-discharge`.
+
+## Dropping in real results
+
+1. Run the test; keep raw logs (thrust stand CSV, Blackbox, thermocouple log) next to the file or
+   in a data store, and list them in `provenance.rawFiles`.
+2. Write `<test-id>.json` with the **same id and column ids** as the stand-in it replaces,
+   `status: "measured"`, real `conditions`, and `provenance.method`, `date`, `operator` or
+   `instruments`. Units must match the columns.
+3. Rebuild: `npx protoboard run tech-docs`. The stand-in generator skips measured
+   files; charts lose the watermark, values get the **M** marker.
+4. Verify: `npx protoboard run tech-docs-verify` fails if a measured chart still carries
+   a watermark, or a stand-in chart lacks one, or a file is malformed.
+
+To add a *new* test, give it a new id and add a chart or table for it in the builder (or a
+test-report document); a file no document reads is still validated.

package/skills/uhd-tech-docs/references/value-queries.md

@@ -0,0 +1,67 @@
+# Value queries
+
+Implementation: `lib/values.ts` (resolver), `format.ts` (formatting),
+`derived.ts` (derivations). The same resolver runs at build and verify time.
+
+## Forms
+
+```
+def:<moduleId>:<path>        field of a module definition (lookup(moduleId))
+inst:<instance path>:<path>  same, by instance path (stack/fc, arm_fl/motor, gnss)
+sys:<path>                   system results
+                               system            the root ModuleDef (links, description…)
+                               checks            checkSystem(SYSTEM): links[], diagnostics[]
+                               bom               docs/<system-id>-bom.json rows (as published)
+                               wiring            wiringChecklist incl. sub-assemblies
+                               scenarios         [{id,label,description,diagnostics}] from scenarios.ts
+                               assembly          {mates, placements, hardware (counts), issues}
+derived:<name>               named derivation
+derived:<fn>(a,b)            parameterised derivation
+ver:<partId>:<path>          the part's verification.json (parts/evidence/<id>/, or vendored with its catalog revision)
+test:<test-id>:<path>        docs/test-data/<test-id>.json
+```
+
+Paths: `.key`, `[n]`, `[key=value]` (first element whose key equals value), `.length`.
+
+```
+def:dolphinrc-f405-v3-flight-controller:interfaces[id=bec_5v].parameters[id=max_current].value
+def:dji-o4-air-unit:traits[type=operating_conditions].params.operating_temperature_C
+def:meps-neon-2207-v2-1950kv:traits[type=performance].params.thrust_tests[0].rows[throttle_pct=100].thrust_g
+sys:checks.diagnostics[id=supply_budget:stack:bec_10v].details.loadW
+sys:system.links[id=stack_mount].mate.gapMm
+test:throttle-sweep:rows[3][4]          (unit = columns[4].unit)
+```
+
+A parameter stated as a `range` resolves `…value` to the range (`[6, 30]` → `6.0–30.0 V`).
+
+## Units
+
+- `parameters[…].value` takes the parameter's `unit`;
+- metadata keys carry units by suffix: `_mm _g _V _A _mA _W _Wh _mAh _ms _s _C _Hz _deg _in _rpm`
+  (`weight_g` → g, `operating_temperature_C` → °C);
+- otherwise pass `u=<unit>` in the format.
+
+## Status
+
+| Status | When | Marker |
+| --- | --- | --- |
+| `source` | a library part with `sources.json` / `verification.json` | none |
+| `model` | a custom module's design value, a UHD check result, a BOM row | none |
+| `assumption` | the module has an `assumption` trait whose `field` names the value | A |
+| `derived` | `derived:` queries (formula + input queries recorded) | D |
+| `standin` | `test:` query on a stand-in file, or a derivation with a stand-in input | S |
+| `measured` | `test:` query on a measured file | M |
+| `gap` | the path resolves to nothing: rendered "—" | — |
+
+## Adding a derivation
+
+```ts
+// lib/derived.ts
+"power.hover_margin": {
+  label: "…", unit: "%", formula: "human-readable formula",
+  compute: (ctx) => ({ value, inputs: ["def:…", "sys:…"], note: "…" }),
+},
+```
+
+Find modules by what they are (`category(def)`), not by id, so the derivation works for other
+systems. Never compute a shown value inside a builder: put it here so the verifier recomputes it.

package/skills/uhd-tech-docs/templates/test-data.example.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "uhd-test-data/1",
+  "id": "hover-current",
+  "title": "Hover current and all-up-weight sensitivity",
+  "status": "measured",
+  "subject": { "system": "quadcopter-5in", "modules": ["meps-neon-2207-v2-1950kv", "cnhl-black-series-1100mah-6s-100c"] },
+  "conditions": [
+    { "name": "Battery nominal", "value": 22.2, "unit": "V" },
+    { "name": "All-up weight (weighed)", "value": 0, "unit": "g" },
+    { "name": "Ambient", "value": 0, "unit": "°C" },
+    { "name": "Firmware", "value": "Betaflight 2025.12.x", "unit": "" }
+  ],
+  "provenance": {
+    "method": "EXAMPLE ONLY — replace every 0 with a measurement. Hover in still air for 60 s per ballast step; current from the FC current sensor (calibrated against a clamp meter), averaged over the steady 40 s.",
+    "date": "YYYY-MM-DD",
+    "operator": "name",
+    "instruments": ["DolphinRC F405 V3 current sensor (Blackbox)", "clamp meter model"],
+    "rawFiles": ["blackbox/LOG00001.BFL"]
+  },
+  "columns": [
+    { "id": "auw", "label": "All-up weight", "unit": "g" },
+    { "id": "thrust_motor", "label": "Hover thrust per motor", "unit": "g" },
+    { "id": "current_total", "label": "Hover current", "unit": "A" },
+    { "id": "power_total", "label": "Hover power", "unit": "W" }
+  ],
+  "rows": [[0, 0, 0, 0]],
+  "summary": [
+    { "id": "auw_g", "label": "All-up weight", "value": 0, "unit": "g" },
+    { "id": "hover_current_A", "label": "Hover current", "value": 0, "unit": "A" },
+    { "id": "hover_power_W", "label": "Hover power", "value": 0, "unit": "W" },
+    { "id": "avionics_current_A", "label": "Avionics current", "value": 0, "unit": "A" }
+  ]
+}

package/skills/uhd-tech-docs/templates/test-data.schema.json

@@ -0,0 +1,213 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "uhd-test-data/1",
+  "title": "UHD document test data",
+  "description": "One test per file: docs/test-data/<id>.json in the project. status standin = derived from the model (watermarked); measured = real results.",
+  "type": "object",
+  "required": [
+    "id",
+    "title",
+    "status",
+    "subject",
+    "conditions",
+    "provenance",
+    "columns",
+    "rows",
+    "summary"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Equals the file name without .json"
+    },
+    "title": {
+      "type": "string"
+    },
+    "status": {
+      "enum": [
+        "standin",
+        "measured"
+      ]
+    },
+    "subject": {
+      "type": "object",
+      "required": [
+        "system"
+      ],
+      "properties": {
+        "system": {
+          "type": "string"
+        },
+        "modules": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "conditions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "value",
+          "unit"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "value": {
+            "type": [
+              "number",
+              "string"
+            ]
+          },
+          "unit": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "method"
+      ],
+      "properties": {
+        "method": {
+          "type": "string"
+        },
+        "derivedFrom": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Value queries (@protoboardai/ext-docs lib/values.ts) a stand-in was derived from"
+        },
+        "assumptions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "generator": {
+          "type": "string"
+        },
+        "generatedAt": {
+          "type": "string"
+        },
+        "operator": {
+          "type": "string"
+        },
+        "date": {
+          "type": "string",
+          "description": "Measured data: ISO date of the test"
+        },
+        "instruments": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rawFiles": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "columns": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "label",
+          "unit"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "unit": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "rows": {
+      "type": "array",
+      "items": {
+        "type": "array",
+        "items": {
+          "type": [
+            "number",
+            "string"
+          ]
+        }
+      }
+    },
+    "summary": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "label",
+          "value",
+          "unit"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "value": {
+            "type": [
+              "number",
+              "string"
+            ]
+          },
+          "unit": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "measured"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "provenance": {
+            "required": [
+              "method",
+              "date"
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/skills/uhd-tech-docs-verify/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: uhd-tech-docs-verify
+description: Verify UHD technical documents (datasheet, assembly guide) against the live model — re-resolve every bound value, check units/format, placeholders, stand-in watermarks, images, pagination and overflow, typography, the BOM file against the model, and assembly coverage of every mate, hardware placement and wiring link (protoboard run tech-docs-verify) — then run a visual review of the page renders. Use after uhd-tech-docs builds, and before handing documents to anyone.
+---
+
+# UHD technical documents — verify
+
+Two stages: the automated verifier, then a visual review of every page. Loop with
+**uhd-tech-docs** until both pass.
+
+## Purpose
+
+Prove that every value in the documents is what the live model says, that
+the layout is clean, and that every mate, hardware placement and wiring link
+is in an assembly step. Use it after every **uhd-tech-docs** build, before
+handing documents to anyone, and before a release packages them. In
+**build-a-project** it closes stage 10.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| Built documents | `docs/<system-id>-*.html`, `*.pdf`, `*.values.json`, `docs/<system-id>-bom.json` | **uhd-tech-docs** |
+| The live model | the project | the project |
+| Tools | `npx protoboard doctor`: `chrome`, `poppler` ✓ | Google Chrome, poppler |
+| The visual checklist | [visual-review](references/visual-review.md) | this skill |
+
+## Steps
+
+### 1. Stage 1: automated
+
+```bash
+npx protoboard run tech-docs-verify                              # all documents
+npx protoboard run tech-docs-verify --input only=assembly --format json
+```
+
+It loads each paginated HTML in headless Chrome, re-loads the project, and writes
+`docs/.review/verify-report.json` plus fresh page PNGs (`docs/.review/<doc>/page-NN.png`, from the
+PDF with pdftoppm). The run fails on any error; its record lists every finding.
+
+| Check | Fails when |
+| --- | --- |
+| values | a `[data-q]` element's text differs from the query re-resolved and re-formatted with its `data-f`, or its status changed (model edited since the build: rebuild) |
+| format | a numeric value lacks the space before its unit; a unit is spelled two ways (warning) |
+| placeholders | visible text contains NaN, undefined, null, `[object Object]`, TODO, TBD, `{{ }}`, Infinity |
+| standin | a stand-in value lacks its S marker; a chart drawn from stand-in data lacks the watermark, or a measured chart still has one; a chart names a missing test file; the legend is missing |
+| images | an `<img>` is missing, fails to decode, or is blank (ink < 0.4 %, flat luminance) |
+| layout | a page body overflows; a table/figure/list is wider than the body; a heading or keep-with-next block is last on a page; a table continuation has < 2 rows; PDF page count ≠ HTML pages; a PDF page is blank |
+| typography | text in a font other than Kode Mono / Kode Mono Bold, fonts not loaded or not embedded, text below 5 pt, more than 16 sizes (warning), system-font fallback in the PDF (warning) |
+| bom | a line of `docs/<id>-bom.json` is missing from the datasheet, the line count differs, or the file is stale against `buildBom()` of the live model |
+| coverage | a mate from `assemble().mates`, a hardware placement from `assemble().hardware`, or a wiring link is in no step (steps record them in `data-mates / data-hardware / data-wiring`); a step lists hardware the model no longer places; automatic steps remain (warning) |
+
+Fix the cause, not the symptom: a value mismatch means rebuild (or a builder computing a value
+outside `values.ts`); a stale BOM means rebuild the documents; coverage gaps mean the
+doc spec's step patterns miss something.
+
+### 2. Stage 2: visual review
+
+Open every PNG in `docs/.review/<doc>/` (an agent can read them as images; use a higher
+`pdftoppm -r 110` render for detail) and walk [the checklist](references/visual-review.md).
+Record findings as `{ doc, page, issue, fix }`, fix them in the builder / CSS / doc spec, rebuild,
+re-verify, and look again. Do not accept a page that only passes the automated checks.
+
+### 3. Report
+
+Summarise: errors fixed, remaining warnings with reasons, the model gaps the documents expose
+(gap markers "—", stand-in assumptions, missing torque/mass/direction data) for the model author.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| A value mismatch | Rebuild first; if it persists, a builder computes a value outside `values.ts`: move it into a query or a derivation. |
+| A warning | Fix it, or state the reason in the report (a unit spelled two ways on purpose is rare). |
+| A page that passes the checks but looks wrong | It fails the review; fix and rebuild. |
+| Model gaps | Reported to the model author; never filled in the document. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| The verifier's report | `docs/.review/verify-report.json` |
+| Page renders | `docs/.review/<doc>/page-NN.png` |
+| The review summary | the report back to the author (and `docs/reviews/` when the project keeps one) |
+
+## Verification
+
+`npx protoboard run tech-docs-verify` succeeds (exit 0, no errors in the
+report), and every page PNG has been looked at with the checklist, with each
+finding fixed or recorded with its reason.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| values check fails | The model changed since the build | `npx protoboard run tech-docs`, then verify again |
+| bom check fails (stale) | The BOM file is older than the model | Rebuild the documents |
+| standin check fails | A watermark or S marker is missing, or a measured chart still has one | Rebuild; check the test-data file's `status` |
+| coverage check fails | A mate, hardware placement or wiring link is in no step | Add it to `assembly.steps` in the doc spec |
+| typography warnings: system-font fallback | A glyph Kode Mono lacks, or `assets/fonts` missing | Rebuild with `run tech-docs`; replace the glyph |
+| `run` refused: tool `chrome` or `poppler` missing | No renderer | Install them, or set `$CHROME` |
+| images check: blank figure | A body without CAD, or a camera that frames nothing | Check the part's artifact (`PB_ARTIFACT_UNAVAILABLE` is expected to show "not available", not blank) and the step's camera |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).

package/skills/uhd-tech-docs-verify/references/visual-review.md

@@ -0,0 +1,43 @@
+# Visual review checklist
+
+For each page PNG in `docs/.review/<doc>/`. Mark each item pass / fix.
+
+## Every page
+
+- [ ] Header band and footer present (not on the cover); page number `NN / NN` matches the
+      contents table.
+- [ ] Nothing cut at the body edge or bottom; no half-empty page caused by a block that could have
+      split (whitespace is fine when a section starts a new page).
+- [ ] One left edge: headings, rules, tables and text align; figures centred or full width.
+- [ ] No text overlapping art, other text, bubbles or leaders; no clipped labels in SVGs.
+- [ ] Type: only the house sizes; no bold/italic fallbacks; no tofu boxes or odd glyphs (µ, Ø, ×, →).
+- [ ] Accent used for highlights only (not body text); red only for warnings/errors.
+
+## Figures (3D)
+
+- [ ] The part(s) of the step are obvious: new parts in dark lines, hardware in accent, context grey.
+- [ ] Exploded parts follow their axis in stacking order and do not collide or hide each other;
+      dashed axes visible through the holes.
+- [ ] Camera matches the previous step unless the step needs another view; nothing important is
+      behind a context part.
+- [ ] Callout bubbles sit outside the silhouette, leaders do not cross each other or pass through
+      other callouts, every bubble matches a letter in the parts strip or a number in the table.
+- [ ] Line weights consistent between figures (similar output width); no aliasing or noise.
+- [ ] Dimensions point at the right features, text readable and bound to a value.
+
+## Tables and charts
+
+- [ ] Header row on tint, numbers right aligned, units consistent, no wrapped one-word columns.
+- [ ] Continued tables repeat their header; no group row orphaned at a page end.
+- [ ] Charts: axes titled with units, ticks readable, legend or labels not overlapping the data.
+- [ ] Every chart from stand-in data shows the watermark and the badge; measured charts show none.
+
+## Content sense
+
+- [ ] Values are plausible (orders of magnitude, units) and identical where repeated.
+- [ ] Assembly steps are in a buildable order, actions are one operation each, quantities match
+      the strip, hardware counts match the hardware page and the coverage appendix.
+- [ ] Wiring tables read pad-to-pad in the right direction; crossovers flagged.
+- [ ] Gap markers (—) and assumptions (A) are visible where the model lacks data, not papered over.
+- [ ] Safety notes present where the model or the doc spec calls for them (props, battery,
+      cooling).