kernelcad-authoring

kernelCAD — authoring

Write or edit .kcad.ts TypeScript models; run kernelcad evaluate <file> or kernelcad export stl|step|dxf|3mf|glb <file> -o <out>.

Single-file scripts refuse top-level import/require with feature.invalid-args; define helpers in the same file.

This file is the core: units, the rules that prevent most failures, which API serves which intent, and the finish checklist. The full reference (every signature, CLI flag, material, recipe) lives in references/*.md beside this file; over MCP pull it with lookup_authoring_skill({ section: '<id>' }) or { query: '...' } (index at the end).

Coordinate System

• Z-up, right-handed. Lengths in millimetres, angles in degrees.
• box(x, y, z): corner-anchored at the origin (spans [0, x] × [0, y] × [0, z]). box(x, y, z, true) centres ALL three axes.
• cylinder(h, r): axis along Z, centred in X/Y, base at z = 0, top at z = h (no centred flag).
• sphere(r): centred on the origin.
• path()...close() builds a Sketch in XY; .extrude(d) goes +Z; .revolve() turns the (radial X, axial Z) profile about Z.
• Return rule: the script returns ONE Shape, or one assembly via assembly(...).model() / .solvedModel(). Only the returned value is exported, probed and measured. A script with no return still evaluates on the last CREATED shape (often a cutter or helper) and gets the warning script.no-return — treat it as a bug and add the return.

Conventions

The rules that prevent most failed evaluations (from the diagnostics catalogue and repair telemetry). Fix the cause, not the symptom.

1. ParamRef arithmetic uses methods. param('w', 60) + 4 throws feature.invalid-args; write w.add(4), w.subtract(t), w.multiply(2), w.divide(4), w.negate(); also .min/.max/.abs/.clamp. Declare params at the top with units; every numeric argument must be finite (NaN/undefined fails capture).
2. Holes are features, not cylinders. Use hole / holes / cutout instead of subtract(cylinder(...)): they drill the right size (threads, counterbores, countersinks), name their faces ('wall', 'floor', 'counterbore-*', 'countersink-cone') and reach drawings, BOM and DFM. Hole u/v are mm offsets from the CENTRE of the entry face (top/bottom: u=+X, v=+Y; front/back: u=+X, v=+Z; left/right: u=+Y, v=+Z), not world coordinates.
3. Booleans need real overlap. Give unions ≥ 0.1 mm of overlap and cut tools ≥ 0.1 mm of run-out past the faces; never rely on coincident or tangent faces. A cut that misses the body is feature.subtractive-noop — check the tool's position and axis.
4. One union, one connected body. union.disconnected = an operand floats; move it until it touches. union.member-overlap = two separately finished pieces of the same stock overlap; fuse first and .finish() once, or butt the members (span - 2 * railWidth).
5. Separate components are named parts. Every physically distinct component is assembly().part(name, shape); parts that touch or move get connectors and a mate ('fastened', 'revolute', 'prismatic', 'cylindrical', 'planar', ...) with limits — not raw translate() offsets. Loose top-level bodies emit assembly.structure.unstructured-bodies.
6. Sketches are one closed loop. Close the path, drop zero-length segments and duplicate points; a revolve profile stays at x ≥ 0 (feature.revolve.crosses-axis).
7. Fillets and chamfers fit the wall. Keep the radius below half the local wall thickness, and every target edge at least 2 × radius long (feature.edge-feature.short-edges-skipped) — round a plate's corners in its outline (extrudeRoundedRect) rather than filleting short vertical edges (repair-oversized-fillet); fillet/chamfer/shell BEFORE the boolean that splits the face (feature.face-ref.ambiguous-after-split) and before transforms when you address faces by name.
8. Face names exist only where a primitive defines them. Box: all six (top, bottom, left, right, front, back); cylinder: top/bottom only; sphere, extruded sketches, extrudeRoundedRect, revolves and lofts: none (feature.face-ref.not-applicable). Pick those faces, and faces a cavity cut duplicated, by query: { byNormal: 'Z' }, { byNormal: '-Z', atZ: 0 } (axis strings 'X', '-X', 'Y', '-Y', 'Z', '-Z').
9. Await async helpers. selectEdges, lib.fromSTEP, lib.fetchPart, .boundingBox(), .recenter() and .seatOnFloor() return promises (feature.async-result.missing-await).
10. Read the diagnostic, then repair one cause. Every diagnostic carries a hint; follow it. recompute.input.missing means an upstream feature failed — call why_did_this_fail. Never export or hand over a script whose last evaluate failed.
11. Do not declare something impossible without calling lookup_api and lookup_cookbook first. kernelCAD does NURBS lofts, sweeps, boundary patches and G2 blends; it is not a polygon sculptor or a photoreal renderer.
12. Helical geometry: rail from helix(...), sweep with spine: 'helix' (threads, worms) or spine: 'smooth' (wire springs). Internal threads are hole({ thread }), never a sweep. .mirror(plane) = source + reflection; .reflect(plane) = reflection only.