WillTools 2026-09-09 -- clean snapshot of the development repo for review

History-free snapshot of the private development repository at 77a82eb.
Code, docs and the public catalogue only: no plant or job knowledge
layers, no client, job or producer names (tools/scrub.py clean against
the widened term list; a second word-level grep clean). The intro deck is
left out because its slide images cannot be checked for job drawings.

knowledge/README.md

@@ -0,0 +1,66 @@
+# `knowledge/` in this checkout
+
+The plant layer and the job layer are not here — never were, never will be
+in a colleague distribution. `catalogue.yaml` **is** here, but it is a
+**carve-out**, not the owner's real file: `tools/make_dist.py`'s
+`build_catalogue_carveout()` reads the real one and re-emits only the
+branches that are trade-standard or that are this tool's own built-in
+configuration, never a manufacturer's product rating. Read the header at
+the top of `catalogue.yaml` itself for the exact list of what's in and
+what's out, and why. `catalogue.yaml.template` is a separate thing: a
+blank-value authoring template for building a real knowledge layer from
+scratch, not what this carve-out is built from.
+
+## Why
+
+WillTools reads its facts in layers, each overriding the one before it:
+
+| layer | where | what it is |
+| --- | --- | --- |
+| `knowledge.DEFAULTS` | in the code | what the tool assumes when nobody has said |
+| `knowledge/catalogue.yaml` | here, carved out | published hardware ratings — manufacturer data |
+| plant layer | `%APPDATA%\WillTools\knowledge.yaml` | one office's naming conventions, casting-bed rails, parameter names |
+| job layer | `<model folder>/_ticketqc/knowledge.yaml` | what this job does differently |
+| project config | wherever the engineer put it | the pinned, merged answer for one job |
+
+The plant and job layers, and `catalogue-rationale.md`, are either a
+specific office's private template or narrate real measured incidents —
+neither belongs in a colleague trial. The catalogue's two real capacity
+tables (`catalogue.inserts`, `connectors.products`) ship **empty** for the
+same reason a manufacturer's rating is not this tool's to redistribute.
+Ask whoever gave you this checkout for the real layers, and the real
+catalogue, once you are ready to point the tools at a real job.
+
+## What runs without the missing pieces
+
+Everything that does not need a lookup: unit conversion, the ribbon itself,
+Self Check, and — outside Revit entirely — `panellift`'s handling
+calculations, which read a frozen job file and never touch `knowledge/` at
+all (see `examples/example-panel.job.json`).
+
+Everything the shipped carve-out covers also runs for real: face
+designations, the up-end orientation rule, ASTM rebar grades, and the whole
+shop-ticket QC checklist (row ids, grades, which check answers which row) —
+none of that needs the real, private file. What stands down cleanly is only
+what actually needs a manufacturer's number: a lifting insert's rated
+capacity, a sandwich-wall tie's rated capacity, and anything downstream of
+either.  `python tools/setup_machine.py --check` reports this state as a
+pass, not a failure — a distribution with the carve-out and no product
+data is an expected, first-class state, not a broken one. Self Check
+reports the same thing inside Revit, row by row.
+
+### Running the test suites here
+
+`CONTRIBUTING.md`'s "What does not run in a trial install" has the full
+accounting. Short version: both suites' `tests/conftest.py` carries an
+appended, auto-detecting block (written by `tools/make_dist.py`'s
+`append_test_exclusions()`) that skips, by name and with a reason, the
+handful of tests that assert the owner's real published numbers rather
+than this tool's logic. Drop in the real `knowledge/catalogue.yaml` and
+those tests un-skip on their own — nothing to edit.
+
+## Getting real knowledge layers
+
+Ask the owner. They come from a second, private repository that is not part
+of this one on purpose — see the top of `.gitignore` in the repo root for
+why the split exists at all.

knowledge/catalogue.yaml.template

@@ -0,0 +1,102 @@
+# TEMPLATE ONLY -- not read by anything. Copy this file's SHAPE, never its
+# content, into a real knowledge/catalogue.yaml if the owner gives you one.
+#
+# This is what `knowledge/catalogue.yaml` looks like: the "published" layer,
+# meant to hold manufacturer data and trade-standard vocabulary that is the
+# same for everyone -- no client, job or plant name belongs in it either.
+# This particular distribution ships with NO catalogue at all (see
+# tools/make_dist.py), so every value below is a placeholder and every
+# section is a skeleton. Do not fill this file in and expect the tools to
+# read it -- see knowledge/README.md for how to get the real one.
+#
+# knowledge._merge_file() treats this file's absence as ordinary: nothing
+# crashes without it, but a few things stand down --
+#
+#   * knowledge.load() falls back to knowledge.DEFAULTS for anything this
+#     file would have overridden -- silent, unremarkable, by design.
+#   * vibe.ticketpage's master shop-ticket checklist (the `checklist.master`
+#     key below) is read from THIS file, and is the one thing that does NOT
+#     degrade quietly if the file is present but broken -- see the comment
+#     above `CHECKLIST_ITEMS` in lib/vibe/ticketpage.py. With no file at
+#     all (this distribution's state) it reports a clear, named reason
+#     instead of a checklist that looks like everything passed.
+
+# ============================================================== face_designations
+# The vocabulary a ticket uses for "which face of the piece" -- near/far
+# (measured from the viewing direction) vs. top/bottom-in-form (measured
+# from the casting bed). Trade abbreviations, not client data.
+face_designations:
+  frames: []                       # e.g. [near_far, top_bottom_in_form]
+  vocabularies: {}
+    # SAMPLE_VOCAB_ID:
+    #   frame: near_far
+    #   measured_from: 'the direction the view looks'
+    #   tokens:
+    #     - {token: 'N.F.', means: 'near face', side: near}
+    #     - {token: 'F.F.', means: 'far face',  side: far}
+
+# ==================================================================== orientation
+# How a plant's model expresses which way a piece is turned. Shape only --
+# every value a real file carries under here is plant knowledge, never here.
+orientation: {}
+
+# ====================================================================== catalogue
+# Manufacturer ratings: lifting inserts, rebar stock lengths, and the safety
+# factors that came with them from a published source. Every real entry
+# carries a `source:` citation (catalogue page, date) because a rating with
+# no citation is not verifiable by the next person who reads it.
+catalogue:
+  safety_factors:
+    tension_fos: null
+    shear_fos: null
+    unknown_because: 'no trade-wide factor to publish -- see a real file for why'
+
+  inserts: {}
+    # SAMPLE_INSERT_PART_NUMBER:
+    #   working_load_lb: 0
+    #   shear_load_lb: 0
+    #   ultimate_tension_lb: 0
+    #   min_edge_distance_in: 0
+    #   safety_factors:
+    #     tension_fos: 0.0
+    #     shear_fos: 0.0
+    #     source: '<manufacturer catalog>, <page>, <date> -- <quoted line>'
+    #   basis_fc_psi: 0
+    #   basis_pcf: 0
+
+  rebar:
+    stock_length_ft: null
+    stock_by_size: {}
+    stock_exempt_marks: []
+
+# ===================================================================== connectors
+# Sandwich-wall wythe-tie products: manufacturer, designation, and every
+# published capacity. Same discipline as `catalogue.inserts` -- a `source:`
+# per entry, an ultimate kept separate from a working load when the vendor
+# never published one.
+connectors:
+  what_it_is: 'the part that crosses a sandwich panel and ties its wythes together'
+  products: {}
+    # 'SAMPLE Manufacturer (SAMPLE-DESIGNATION)':
+    #   manufacturer: 'SAMPLE Manufacturer'
+    #   designation: SAMPLE-DESIGNATION
+    #   tie_length_in: 0.0
+    #   ultimate_tensile_pullout_lb: 0
+    #   capacity_lb: null
+    #   capacity_unknown_because: 'vendor publishes no working load or factor'
+
+# ====================================================================== checklist
+# The master shop-ticket checklist: what exists, how each row is worded, and
+# what grade (A/B/C/D) it carries. Same at every plant -- a plant selects
+# and mutes from here, never redefines a row. See `MASTER_KEY` in
+# lib/vibe/ticketpage.py for exactly how this is read, and its own comment
+# for why a file that is PRESENT but broken refuses loudly rather than
+# quietly running a shorter checklist.
+checklist:
+  master: []
+    # - id: '1.1'
+    #   name: 'Sheet name equals the piece mark'
+    #   grade: 'A'
+    #   owner_codes: ['SAMPLE-CODE']
+    #   not_run_reason: null
+    #   checks: 'check_sample_thing'   # a function name in ticketchecks.py