cad-khana
cad-khana splits geometric reasoning into two workflows:
- Mechanism — relational checks on an assembly (no interference,
clearance between parts). Expressed via
Assembly.assert_*(...) and
evaluated by khana check. Writes mechanism.json.
- Printability — per-part, per-manufacturing-method checks (min
wall thickness, overhangs). Expressed via
inspect(part, method=...).
Writes <name>-printability.json.
Declarations are imported by verbs; effects live at the CLI
boundary. A module that declares parts, assemblies and claims calls
nothing effectful — no check(), no inspect(), no export. khana check imports it and evaluates; khana export imports the same file
and writes STL/STEP; khana draw draws it. Genuinely imperative work
(batches, sweeps) goes in a separate script behind khana run.
A declaration module therefore has no if __name__ == "__main__"
block — nothing executes it. See The three file kinds.
Setup
If khana --version fails, follow references/install.md once before
proceeding.
When to use this tool
- Designing a multi-part mechanical assembly that needs to fit
together (hinges, snap-fits, sliders, clevis/pin joints, boxes with
lids).
- Producing printable geometry where wall thickness, clearance, and
overhangs matter.
- Iterating under agent control — the JSON diagnostics are the
primary signal;
khana draw supplements it with engineering-drawing
PNGs (HLR line-art) you can read directly when shape-level questions
come up.
When not to use it
- Pure surface modeling, organic shapes, meshes from scans. Use
Build123d directly or a mesh tool.
- CAM / toolpath generation. Out of scope.
- Full constraint solving (drive geometry from relationships). The tool
uses assertions — they check, they don't drive.
CLI
Two kinds of command. Import-model verbs take a target, import
the module, resolve one member, and do one thing to it. Execute-model
runs a script for effect.
khana check <target> # diagnostics + assertions → mechanism.json
khana export <target> # STL + STEP
khana view <target> # write the assembly as a viewer page (outputs/page/)
khana draw <target> [--view <names>] [--part <name>] [--format png|svg|both] [--themeable]
khana run <script> # execute an orchestration script
khana diff <before> <after> # diff two JSON files; exit 0 identical, 1 differences, 2 error
khana show <json> [--grep <re>] [--failed] [--skipped] [--sort value] [--group <re>] [--json] # read one JSON; see references/cli.md
khana status # JSON probe of versions and bun; exit nonzero if degraded
khana --version
khana check is the primary loop. It never exports — STL/STEP come
from khana export, and the two read the same file, so there is no
toggle to get wrong and no way for check-only geometry to reach an
export.
JSON diagnostics are always written, even on failure — read them to
diagnose errors. Exit codes: 2 for a usage error (unresolvable
target, unknown --view), 1 for a failed run.
A target is <module-path>[:<factory>]; with no :factory the verb
uses the module's assembly member. How members resolve, where output
lands, how imports resolve and how to serve the viewer page:
references/cli.md.
The three file kinds
Name a file by what it is. The name is the whole tell — a reader
should know from it whether the file declares, verifies, or
orchestrates.
| kind |
name |
addressed by |
imported by others? |
| declaration module |
assembly.py, animated_assembly.py |
khana check / export / view / draw |
yes — this is the product |
| check module |
check_*.py |
khana check |
never |
| command script |
a descriptive noun — printability.py, role_sweep.py |
khana run |
never |
What goes in a declaration module, in order, is in
references/style.md; a family of members the CLI can't address one
by one (roles, frames) is a command script — references/cli.md
§Parametrized families.
Check module
An ordinary assembly module whose purpose is verification. It imports
product factories, composes a fixture, declares claims about the
interaction, and exposes the result as a factory. Prefix check_.
The never-imported rule: product modules never import check
modules — the same rule that keeps test files out of shipped code.
That is what makes assertion-only geometry free
(references/composition.md).
A claim belongs in the builder, a check module, or a check module for
one assembly step, depending on when it has to hold
(references/composition.md §Where a claim lives).
Command script
Orchestration only: loops, batches, and the effectful calls the verbs
don't cover. Never a claim that a verb could have evaluated.
printability.py is the name for a unit's inspect() batch. It
names its output, it is a noun, and it can't be mistaken for a
check_*.py.
<family>_sweep.py for a parametrized family the CLI cannot
address (role_sweep.py, frame_sweep.py).
- No
run_ prefix — khana run .../run_printability.py stutters,
and the directory position already says what the file is.
- Open the docstring with its own invocation line, then a sentence
saying which member
khana check on the sibling assembly.py
covers and which it does not. That sentence is load-bearing: without
it, "I ran khana check, it was green" silently means one role, one
frame, or no printability at all.
See references/examples/pin_hinge/ for a worked declaration module
plus command script.
Vacuous green
khana check on a module that declares no assertions exits 0 and
writes "assertions": []. That is not a passing design; it is an
unasked question, and an agent will read it as success. Modules that
strip assertions by design (an exhibit or render-only variant) should
say so in the first line of the docstring and carry a name that marks
them — a reader who sees animated_exhibit_assembly.py go green
should already know that means nothing. Check assertions is
non-empty before believing a green run on an unfamiliar file.
Minimal skeleton
assembly.py — the declaration module. Note what is absent: no
check(), no inspect(), no __main__.
from build123d import Box, Cylinder, Location, Part, Pos, Rot
from cad_khana.mechanism.assembly import Assembly
# 1. parameters + derived
WIDTH = 40.0
HEIGHT = 20.0
PIN_D = 3.0
PIN_GAP = 0.4 # rest gap between pin and bracket top
PIN_Z = HEIGHT + PIN_D / 2 + PIN_GAP
# 2. pure part functions
def bracket(w: float = WIDTH, h: float = HEIGHT) -> Part:
return Pos(0, 0, h / 2) * Box(w, w, h)
def pin(length: float = WIDTH, d: float = PIN_D) -> Part:
return Cylinder(d / 2, length)
# 3. factory — defaults are the master design
def build_mount(pin_gap: float = PIN_GAP) -> Assembly:
pin_z = HEIGHT + PIN_D / 2 + pin_gap
return (
Assembly()
.with_part("bracket", bracket())
.with_part("pin", pin(), location=Location((0, 0, pin_z)) * Rot(90, 0, 0))
.assert_no_interference("pin", "bracket")
.assert_distance("pin", "bracket", min_mm=pin_gap * 0.9)
)
# 4. degenerate memoized master, so `khana check <file>` resolves
assembly = build_mount()
printability.py — the command script beside it:
"""Per-part printability.
khana run unit/printability.py
`khana check` on the sibling `assembly.py` covers the mechanism claims.
It does not cover anything in this file.
"""
from cad_khana.printability.inspect import inspect
from cad_khana.printability.methods import FDM
from assembly import bracket
inspect(bracket(), method=FDM(), out="outputs", name="bracket")
A two-part mechanism with no relocatable unit and no joint is the
degenerate flat case — anything with either composes sub-assemblies
(see references/workflow.md §Designing a new mechanism, step 2, and
references/composition.md).
What a green check does not mean
Exit 0 means no interference and printability passed, for the claims
you declared, at the poses you built. Each of the following is a real
defect class a green check cannot see. When a slice depends on one of
them, the check is not your evidence — find the one that is.
- Unasserted geometry. A dimension consumed only by cosmetic
geometry never earns an assertion, so it silently tracks whatever it
was derived from. Nothing here measures appearance, and nothing sees
a camera.
khana draw is how you find the claims you forgot to make
— draw a view before believing a green on a part whose parameters
moved. Check assertions is non-empty first (see Vacuous green).
- Orientation. A wrong outward normal is not an overlap: a part
placed facing backwards passes every clearance claim. When facing
carries function,
assert_tangent_contact against the surface it
must face — that pins the orientation too.
- One pose. A claim with
poses.evaluated: 1 looked once, at the
pose you built. It says nothing about the sign of a motion (a
docstring claiming kinematics is not evidence — check at a non-rest
pose), nothing about a service or removal path, and nothing about the
pose where the envelope is actually worst. Declare a Motion and the
claims are held at every sample; where you can't, say beside the
assert which pose the numbers came from, or it expires silently when
the parameter moves.
- Promotion widens a claim's scope. A bare
assert over constants
is frozen at that pose; a declared assert_distance is re-evaluated
at every pose a motion builds. Promoting a rest-pose claim therefore
reddens frames where nothing is wrong. Ask which poses the claim was
ever true at, scope it with during=, and run the motion — not just
the unit's own khana check.
- A standalone green is a weaker claim than a top-level green.
Claims referencing parts a run doesn't contain are skipped, not
failed: read
skipped_counts, not just the exit code. A detail tier
that isn't applied skips the claims that were written for it.
- Cross-unit physical reality. Two independently floor-standing
units pass every cross-unit check while being unbuildable — they
share one bench, and nothing infers that. Export the shared datum as
an anchor and
assert_anchors_coincident at the top
(references/composition.md §Named interface anchors).
One habit that keeps the rest honest: turn every fixed interference
into a named regression assert, and write a known-bad overlap as
assert_interference(reason=…) rather than deleting the claim. A
positive assertion self-fails the moment the redesign lands, so it
cannot rot into folklore.
Read warnings on every run
Both files carry a warnings[] that never fails a run — which is
exactly why it is where a green says what it did not look at. Read it
before believing an exit 0. Every kind:
joint_never_driven — a joint no declared motion moves; everything
about it is a rest-pose green.
never_in_phase — a phased claim whose during= window no pose
entered: widen the motion or fix the window.
motion_moved_nothing (motion, moved, movable) — a declared
motion that moved no claim: the sweep is vacuous and the green
means nothing, so check the joint path drives something a claim
references; with movable: 0 no claim in the tree could have moved.
interferences_rest_pose_only — a motion is declared, and
interferences[] did not follow it: unasserted pairs are checked at
the as-built pose only.
partial_run (evaluated, declared) — khana check --only held
a subset and computed no interferences: a green here is not the model's.
multi_solid (part, solid_count) — a part of several solids,
apart or overlapping, that no assert_solid_count /
inspect(..., solid_count=N) speaks for: bound it or declare it.
Nothing else sees a severed part. A declared count does not say the
solids are apart.
not_solid (part, solid_count) — a part with faces outside any
solid: a shell, a face, or one beside a solid. It holds no material, so
it is left out of interferences[], its volume_mm3 is null, and
every overlap claim on it fails. A surface on purpose declares
assert_solid_count(part, eq=0); otherwise wrap it in Solid(...).
empty_solid (part, empty_solids) — a part with a solid of zero
volume, which an outline folded onto itself extrudes to. It is valid
and counts as a solid, but holds no material: it is left out of
interferences[] and every overlap claim on it fails. Rebuild it.
waived_failure (printability) — a failed check you waived; carries
the reason and the failure detail. The reading is still a failure.
stale_waiver (printability) — a waiver whose check now passes:
delete it.
Next to warnings, read skipped_counts (a claim that did not look)
and each assertion's poses.evaluated (1 means it looked once). The
rest of both files' fields: references/diagnostics.md.
Known limitations
- Min wall thickness is approximate. Rays are cast from tessellated
faces against the exact solid, and each ray measures only where it
crosses the face it was cast from — perpendicular to that face, so
the reading is a thickness of that wall. It can still miss diagonal
pinch points. Readings at sharp features are real short material
paths rather than noise — check
min_wall_alignment to tell a wedge
tip from a wall. See references/printability.md.
- Overhang detection excludes the build-plate face. Faces coplanar
with the min-
up_axis plane aren't flagged. Faces that face downward
but sit above the build plate (ledge undersides, cavity ceilings) are
still flagged.
- Interference check is O(n²) over parts. Fine up to ~20 parts.
- Tangent contact reads as zero clearance. Two parts sharing a face
(e.g., a lid sitting on a rim) have
distance_to == 0, which fails
any assert_distance(min_mm=…) above zero by definition. Use
assert_no_interference when parts are meant to touch.
Reference files
Load each when its trigger applies — they are not optional reading
for the task they cover. Every library name a script needs is in the
last column, beside the file that documents it: a name you can't find
here isn't in the library, and one you can is already documented, so
load that file before proposing a feature.
| Load |
before |
names |
references/workflow.md |
starting a mechanism from a blank file, or the same failure surviving three fix attempts — design order, the check-then-draw loop, when to stop and escalate with HUMAN_REVIEW: |
|
references/cli.md |
addressing a :factory, looking for an output file, keeping a script's outputs apart (before/after baselines, parallel runs), an import failing under khana, the viewer, or checking several members of a family |
check, export_assembly |
references/style.md |
writing or restructuring a declaration module — a part function, helper or factory, or adding, moving or deriving a parameter (changing an existing parameter's value alone doesn't fire it) |
Assembly, with_part, with_materials, with_detailed_geometry |
references/assertions.md |
writing or changing any assert_* — the catalogue, solid count, distance/scalar, contact claims and during=, group assertions |
every assert_*, with_keepout, with_region, swept |
references/composition.md |
adding a sub-assembly, joint or anchor, a claim about two units, or querying a composed assembly from a script (posing a joint, finding a placed part) |
with_subassembly, part(path), placed_parts, with_anchor, anchor, with_joint, with_joint_angle |
references/motion.md |
anything that moves or animates — declared motions, sweeps, GLB export |
Motion, with_motion, posed, over_joint, over_motion, sweep, classify, onset, export_glb, export_animated_glb |
references/printability.md |
an inspect() call, a waiver, a printability JSON, or choosing a print orientation |
inspect, FDM, Waiver, Feature |
references/render.md |
a photo-real render, a PBR GLB or an mp4 of an assembly, or editing a script that imports cad_khana.render — needs the optional render extra (Blender) |
Scene, render, render_animation, render_animation_from_glb, FixedPose, the PBR export_glb |
references/diagnostics.md |
reading any JSON field beyond status, passed, skipped_counts and warnings |
|
references/drawings.md |
khana draw — which view answers which question |
|
references/viewer.md |
the owner pointing at a part or a view in the viewer page ("this part", "from here"), or showing them one — khana viewer, whose state names what the owner picked |
|
references/build123d_quickref.md |
selector operators, algebraic vs Builder mode, type-conversion shortcuts |
|
references/standard_parts.md |
any standard hardware (bd_warehouse) |
|
references/examples/pin_hinge/ |
a worked three-part mechanism with assertions and inspect() calls |
|
Feedback
cad-khana is young — actively log feedback whenever something is
awkward, buggy, missing, surprising, or took more work than it
should. Don't filter; the maintainer triages.
When cad-khana is editably installed (e.g.
[tool.uv.sources] cad-khana = { path = "../cad-khana", editable = true }),
append a short entry to <cad-khana-repo>/_notes/field-notes.md — that
file's header has the entry format. When installed as a tool from
git, file an issue at https://github.com/cyberchitta/cad-khana/issues
with the same content.
A pattern only emerges when individual observations are recorded
honestly, so log first and worry about whether it generalizes later.
1---2name: cad-khana3description: "Diagnostics-first CAD wrapper around Build123d: assembly-level interference/clearance assertions plus optional per-part printability checks. Load BEFORE editing an `assembly.py` that uses the wrapper or interpreting its diagnostic JSON — SKILL.md has conventions the scripts rely on but don't restate, including which of three file kinds you are editing, and names the reference file to load for each task. TRIGGER: about to run `khana check`/`export`/`view`/`draw`/`run`, or editing a file that imports `cad_khana` or calls `Assembly()`/`check()`/`inspect()`."4metadata:5 source: https://skillmd.com/skills/cyberchitta/cad-khana6---78# cad-khana910cad-khana splits geometric reasoning into two workflows:1112- **Mechanism** — relational checks on an assembly (no interference,13 clearance between parts). Expressed via `Assembly.assert_*(...)` and14 evaluated by `khana check`. Writes `mechanism.json`.15- **Printability** — per-part, per-manufacturing-method checks (min16 wall thickness, overhangs). Expressed via `inspect(part, method=...)`.17 Writes `<name>-printability.json`.1819**Declarations are imported by verbs; effects live at the CLI20boundary.** A module that declares parts, assemblies and claims calls21nothing effectful — no `check()`, no `inspect()`, no export. `khana22check` imports it and evaluates; `khana export` imports the same file23and writes STL/STEP; `khana draw` draws it. Genuinely imperative work24(batches, sweeps) goes in a separate script behind `khana run`.2526A declaration module therefore has **no `if __name__ == "__main__"`27block** — nothing executes it. See **The three file kinds**.2829## Setup3031If `khana --version` fails, follow `references/install.md` once before32proceeding.3334## When to use this tool3536- Designing a **multi-part mechanical assembly** that needs to fit37 together (hinges, snap-fits, sliders, clevis/pin joints, boxes with38 lids).39- Producing **printable geometry** where wall thickness, clearance, and40 overhangs matter.41- Iterating under **agent control** — the JSON diagnostics are the42 primary signal; `khana draw` supplements it with engineering-drawing43 PNGs (HLR line-art) you can read directly when shape-level questions44 come up.4546## When not to use it4748- Pure surface modeling, organic shapes, meshes from scans. Use49 Build123d directly or a mesh tool.50- CAM / toolpath generation. Out of scope.51- Full constraint solving (drive geometry from relationships). The tool52 uses *assertions* — they check, they don't drive.5354## CLI5556Two kinds of command. **Import-model verbs** take a *target*, import57the module, resolve one member, and do one thing to it. **Execute-model**58runs a script for effect.5960```61khana check <target> # diagnostics + assertions → mechanism.json62khana export <target> # STL + STEP63khana view <target> # write the assembly as a viewer page (outputs/page/)64khana draw <target> [--view <names>] [--part <name>] [--format png|svg|both] [--themeable]65khana run <script> # execute an orchestration script66khana diff <before> <after> # diff two JSON files; exit 0 identical, 1 differences, 2 error67khana show <json> [--grep <re>] [--failed] [--skipped] [--sort value] [--group <re>] [--json] # read one JSON; see references/cli.md68khana status # JSON probe of versions and bun; exit nonzero if degraded69khana --version70```7172`khana check` is the primary loop. It never exports — STL/STEP come73from `khana export`, and the two read the *same* file, so there is no74toggle to get wrong and no way for check-only geometry to reach an75export.7677JSON diagnostics are always written, even on failure — read them to78diagnose errors. Exit codes: **2** for a usage error (unresolvable79target, unknown `--view`), **1** for a failed run.8081A target is `<module-path>[:<factory>]`; with no `:factory` the verb82uses the module's `assembly` member. How members resolve, where output83lands, how imports resolve and how to serve the viewer page:84`references/cli.md`.8586## The three file kinds8788Name a file by what it *is*. The name is the whole tell — a reader89should know from it whether the file declares, verifies, or90orchestrates.9192| kind | name | addressed by | imported by others? |93|---|---|---|---|94| **declaration module** | `assembly.py`, `animated_assembly.py` | `khana check` / `export` / `view` / `draw` | yes — this is the product |95| **check module** | `check_*.py` | `khana check` | **never** |96| **command script** | a descriptive noun — `printability.py`, `role_sweep.py` | `khana run` | never |9798What goes in a declaration module, in order, is in99`references/style.md`; a family of members the CLI can't address one100by one (roles, frames) is a command script — `references/cli.md`101§Parametrized families.102103### Check module104105An ordinary assembly module whose *purpose* is verification. It imports106product factories, composes a fixture, declares claims about the107interaction, and exposes the result as a factory. Prefix `check_`.108109**The never-imported rule: product modules never import check110modules** — the same rule that keeps test files out of shipped code.111That is what makes assertion-only geometry free112(`references/composition.md`).113114A claim belongs in the builder, a check module, or a check module for115one assembly step, depending on when it has to hold116(`references/composition.md` §Where a claim lives).117118### Command script119120Orchestration only: loops, batches, and the effectful calls the verbs121don't cover. Never a claim that a verb could have evaluated.122123- **`printability.py`** is the name for a unit's `inspect()` batch. It124 names its output, it is a noun, and it can't be mistaken for a125 `check_*.py`.126- **`<family>_sweep.py`** for a parametrized family the CLI cannot127 address (`role_sweep.py`, `frame_sweep.py`).128- **No `run_` prefix** — `khana run .../run_printability.py` stutters,129 and the directory position already says what the file is.130- **Open the docstring with its own invocation line**, then a sentence131 saying which member `khana check` on the sibling `assembly.py`132 covers and which it does not. That sentence is load-bearing: without133 it, "I ran `khana check`, it was green" silently means one role, one134 frame, or no printability at all.135136See `references/examples/pin_hinge/` for a worked declaration module137plus command script.138139### Vacuous green140141`khana check` on a module that declares **no assertions** exits 0 and142writes `"assertions": []`. That is not a passing design; it is an143unasked question, and an agent will read it as success. Modules that144strip assertions by design (an exhibit or render-only variant) should145say so in the first line of the docstring and carry a name that marks146them — a reader who sees `animated_exhibit_assembly.py` go green147should already know that means nothing. Check `assertions` is148non-empty before believing a green run on an unfamiliar file.149150## Minimal skeleton151152`assembly.py` — the declaration module. Note what is *absent*: no153`check()`, no `inspect()`, no `__main__`.154155```python156from build123d import Box, Cylinder, Location, Part, Pos, Rot157158from cad_khana.mechanism.assembly import Assembly159160# 1. parameters + derived161WIDTH = 40.0162HEIGHT = 20.0163PIN_D = 3.0164PIN_GAP = 0.4 # rest gap between pin and bracket top165PIN_Z = HEIGHT + PIN_D / 2 + PIN_GAP166167# 2. pure part functions168def bracket(w: float = WIDTH, h: float = HEIGHT) -> Part:169 return Pos(0, 0, h / 2) * Box(w, w, h)170171def pin(length: float = WIDTH, d: float = PIN_D) -> Part:172 return Cylinder(d / 2, length)173174# 3. factory — defaults are the master design175def build_mount(pin_gap: float = PIN_GAP) -> Assembly:176 pin_z = HEIGHT + PIN_D / 2 + pin_gap177 return (178 Assembly()179 .with_part("bracket", bracket())180 .with_part("pin", pin(), location=Location((0, 0, pin_z)) * Rot(90, 0, 0))181 .assert_no_interference("pin", "bracket")182 .assert_distance("pin", "bracket", min_mm=pin_gap * 0.9)183 )184185# 4. degenerate memoized master, so `khana check <file>` resolves186assembly = build_mount()187```188189`printability.py` — the command script beside it:190191```python192"""Per-part printability.193194 khana run unit/printability.py195196`khana check` on the sibling `assembly.py` covers the mechanism claims.197It does not cover anything in this file.198"""199from cad_khana.printability.inspect import inspect200from cad_khana.printability.methods import FDM201202from assembly import bracket203204inspect(bracket(), method=FDM(), out="outputs", name="bracket")205```206207A two-part mechanism with no relocatable unit and no joint is the208degenerate flat case — anything with either composes sub-assemblies209(see `references/workflow.md` §Designing a new mechanism, step 2, and210`references/composition.md`).211212## What a green check does not mean213214Exit 0 means *no interference and printability passed, for the claims215you declared, at the poses you built*. Each of the following is a real216defect class a green check cannot see. When a slice depends on one of217them, the check is not your evidence — find the one that is.218219- **Unasserted geometry.** A dimension consumed only by cosmetic220 geometry never earns an assertion, so it silently tracks whatever it221 was derived from. Nothing here measures appearance, and nothing sees222 a camera. `khana draw` is how you find the claims you forgot to make223 — draw a view before believing a green on a part whose parameters224 moved. Check `assertions` is non-empty first (see **Vacuous green**).225- **Orientation.** A wrong outward normal is not an overlap: a part226 placed facing backwards passes every clearance claim. When facing227 carries function, `assert_tangent_contact` against the surface it228 must face — that pins the orientation too.229- **One pose.** A claim with `poses.evaluated: 1` looked once, at the230 pose you built. It says nothing about the sign of a motion (a231 docstring claiming kinematics is not evidence — check at a non-rest232 pose), nothing about a service or removal path, and nothing about the233 pose where the envelope is actually worst. Declare a `Motion` and the234 claims are held at every sample; where you can't, say beside the235 assert which pose the numbers came from, or it expires silently when236 the parameter moves.237- **Promotion widens a claim's scope.** A bare `assert` over constants238 is frozen at that pose; a declared `assert_distance` is re-evaluated239 at every pose a motion builds. Promoting a rest-pose claim therefore240 reddens frames where nothing is wrong. Ask which poses the claim was241 ever true at, scope it with `during=`, and run the motion — not just242 the unit's own `khana check`.243- **A standalone green is a weaker claim than a top-level green.**244 Claims referencing parts a run doesn't contain are skipped, not245 failed: read `skipped_counts`, not just the exit code. A detail tier246 that isn't applied skips the claims that were written for it.247- **Cross-unit physical reality.** Two independently floor-standing248 units pass every cross-unit check while being unbuildable — they249 share one bench, and nothing infers that. Export the shared datum as250 an anchor and `assert_anchors_coincident` at the top251 (`references/composition.md` §Named interface anchors).252253One habit that keeps the rest honest: **turn every fixed interference254into a named regression assert**, and write a known-bad overlap as255`assert_interference(reason=…)` rather than deleting the claim. A256positive assertion self-fails the moment the redesign lands, so it257cannot rot into folklore.258259### Read `warnings` on every run260261Both files carry a `warnings[]` that **never fails a run** — which is262exactly why it is where a green says what it did not look at. Read it263before believing an exit 0. Every kind:264265- `joint_never_driven` — a joint no declared motion moves; everything266 about it is a rest-pose green.267- `never_in_phase` — a phased claim whose `during=` window no pose268 entered: widen the motion or fix the window.269- `motion_moved_nothing` (`motion`, `moved`, `movable`) — a declared270 motion that moved **no** claim: the sweep is vacuous and the green271 means nothing, so check the joint path drives something a claim272 references; with `movable: 0` no claim in the tree could have moved.273- `interferences_rest_pose_only` — a motion is declared, and274 `interferences[]` did not follow it: unasserted pairs are checked at275 the as-built pose only.276- `partial_run` (`evaluated`, `declared`) — `khana check --only` held277 a subset and computed no interferences: a green here is not the model's.278- `multi_solid` (`part`, `solid_count`) — a part of several solids,279 apart or overlapping, that no `assert_solid_count` /280 `inspect(..., solid_count=N)` speaks for: bound it or declare it.281 Nothing else sees a severed part. A declared count does not say the282 solids are apart.283- `not_solid` (`part`, `solid_count`) — a part with faces outside any284 solid: a shell, a face, or one beside a solid. It holds no material, so285 it is left out of `interferences[]`, its `volume_mm3` is `null`, and286 every overlap claim on it fails. A surface on purpose declares287 `assert_solid_count(part, eq=0)`; otherwise wrap it in `Solid(...)`.288- `empty_solid` (`part`, `empty_solids`) — a part with a solid of zero289 volume, which an outline folded onto itself extrudes to. It is valid290 and counts as a solid, but holds no material: it is left out of291 `interferences[]` and every overlap claim on it fails. Rebuild it.292- `waived_failure` (printability) — a failed check you waived; carries293 the reason and the failure detail. The reading is still a failure.294- `stale_waiver` (printability) — a waiver whose check now passes:295 delete it.296297Next to `warnings`, read `skipped_counts` (a claim that did not look)298and each assertion's `poses.evaluated` (`1` means it looked once). The299rest of both files' fields: `references/diagnostics.md`.300301## Known limitations302303- **Min wall thickness is approximate.** Rays are cast from tessellated304 faces against the exact solid, and each ray measures only where it305 crosses the face it was cast from — perpendicular to that face, so306 the reading is a thickness of *that* wall. It can still miss diagonal307 pinch points. Readings at sharp features are *real* short material308 paths rather than noise — check `min_wall_alignment` to tell a wedge309 tip from a wall. See `references/printability.md`.310- **Overhang detection excludes the build-plate face.** Faces coplanar311 with the min-`up_axis` plane aren't flagged. Faces that face downward312 but sit above the build plate (ledge undersides, cavity ceilings) are313 still flagged.314- **Interference check is O(n²)** over parts. Fine up to ~20 parts.315- **Tangent contact reads as zero clearance.** Two parts sharing a face316 (e.g., a lid sitting on a rim) have `distance_to == 0`, which fails317 any `assert_distance(min_mm=…)` above zero by definition. Use318 `assert_no_interference` when parts are meant to touch.319320## Reference files321322Load each when its trigger applies — they are not optional reading323for the task they cover. Every library name a script needs is in the324last column, beside the file that documents it: a name you can't find325here isn't in the library, and one you can is already documented, so326load that file before proposing a feature.327328| Load | before | names |329|---|---|---|330| `references/workflow.md` | starting a mechanism from a blank file, or the same failure surviving three fix attempts — design order, the check-then-draw loop, when to stop and escalate with `HUMAN_REVIEW:` | |331| `references/cli.md` | addressing a `:factory`, looking for an output file, keeping a script's outputs apart (before/after baselines, parallel runs), an import failing under `khana`, the viewer, or checking several members of a family | `check`, `export_assembly` |332| `references/style.md` | writing or restructuring a declaration module — a part function, helper or factory, or adding, moving or deriving a parameter (changing an existing parameter's value alone doesn't fire it) | `Assembly`, `with_part`, `with_materials`, `with_detailed_geometry` |333| `references/assertions.md` | writing or changing any `assert_*` — the catalogue, solid count, distance/scalar, contact claims and `during=`, group assertions | every `assert_*`, `with_keepout`, `with_region`, `swept` |334| `references/composition.md` | adding a sub-assembly, joint or anchor, a claim about two units, or querying a composed assembly from a script (posing a joint, finding a placed part) | `with_subassembly`, `part(path)`, `placed_parts`, `with_anchor`, `anchor`, `with_joint`, `with_joint_angle` |335| `references/motion.md` | anything that moves or animates — declared motions, sweeps, GLB export | `Motion`, `with_motion`, `posed`, `over_joint`, `over_motion`, `sweep`, `classify`, `onset`, `export_glb`, `export_animated_glb` |336| `references/printability.md` | an `inspect()` call, a waiver, a printability JSON, or choosing a print orientation | `inspect`, `FDM`, `Waiver`, `Feature` |337| `references/render.md` | a photo-real render, a PBR GLB or an mp4 of an assembly, or editing a script that imports `cad_khana.render` — needs the optional `render` extra (Blender) | `Scene`, `render`, `render_animation`, `render_animation_from_glb`, `FixedPose`, the PBR `export_glb` |338| `references/diagnostics.md` | reading any JSON field beyond `status`, `passed`, `skipped_counts` and `warnings` | |339| `references/drawings.md` | `khana draw` — which view answers which question | |340| `references/viewer.md` | the owner pointing at a part or a view in the viewer page ("this part", "from here"), or showing them one — `khana viewer`, whose `state` names what the owner picked | |341| `references/build123d_quickref.md` | selector operators, algebraic vs Builder mode, type-conversion shortcuts | |342| `references/standard_parts.md` | any standard hardware (bd_warehouse) | |343| `references/examples/pin_hinge/` | a worked three-part mechanism with assertions and `inspect()` calls | |344345## Feedback346347cad-khana is young — actively log feedback whenever something is348awkward, buggy, missing, surprising, or took more work than it349should. Don't filter; the maintainer triages.350351When cad-khana is editably installed (e.g.352`[tool.uv.sources] cad-khana = { path = "../cad-khana", editable = true }`),353append a short entry to `<cad-khana-repo>/_notes/field-notes.md` — that354file's header has the entry format. When installed as a tool from355git, file an issue at https://github.com/cyberchitta/cad-khana/issues356with the same content.357358A pattern only emerges when individual observations are recorded359honestly, so log first and worry about whether it generalizes later.