Skip to content

feat(cookbook): index mechanism/assembly snippets for lookup_cookbook - #688

Merged
w1ne merged 2 commits into
developfrom
fix/cookbook-mechanism-snippets
Aug 25, 2026
Merged

feat(cookbook): index mechanism/assembly snippets for lookup_cookbook#688
w1ne merged 2 commits into
developfrom
fix/cookbook-mechanism-snippets

Conversation

@w1ne

@w1ne w1ne commented Aug 25, 2026

Copy link
Copy Markdown
Owner

The gap (KC-10)

lookup_cookbook had no reachable mechanism content. Every one of these returned single-body geometry instead — the top hit for the first was a snippet about mirroring a symmetric part:

  • "assembly with parts connectors and mates"
  • "hinge"
  • "revolute joint"
  • "how do I declare a connector"

The cost is bigger than discoverability. A connector origin must use the tagged form:

base.connector('pivot', { type: 'axis', origin: { kind: 'vec3', value: [5, 20, 16] }, axis: [0, 1, 0] });
arm.mate('elbow', 'base.pivot', 'arm.pivot', 'revolute', { limitsDeg: [0, 90] });

A bare [x, y, z] array instead crashes the evaluator with an unhandled Cannot read properties of undefined (reading 'kind') — an internal TypeError, not a validation diagnostic. That tagged form appears in no tool documentation. The only place it was written down was cookbook source that lookup_cookbook could not reach, so the discovery tool couldn't surface the one fact that prevents the crash.

The change

Two snippets in the indexed corpus — a two-link arm (connector + revolute mate) and a clamshell hinge — the six tags that make them findable, and a test asserting all four queries return a mechanism snippet and that the returned body shows the tagged origin form.

Verification

  • Both snippets actually execute against the live engine: ok: true, 2 parts, zero diagnostics, for each. A cookbook snippet that doesn't run is worse than no snippet, so this was checked rather than assumed.
  • Negative control: with the two snippet files removed, all 5 tests fail; restored, all 5 pass.
  • src/agent: 362 passed, 0 failed (run in a checkout with generated assets present).
  • tsc --noEmit: clean.

One note for anyone verifying in a fresh worktree: assets/parts/ is gitignored and generated, so fetchPart / findPart / listPartCategories / listPartFamilies fail there for that reason alone. They pass in a normal checkout.

Known limitation

This indexes the root cookbook/ corpus. The worked examples under src/agent/skills/kernelcad-kinematic/cookbook/*.kcad.ts (scissor jack, over-centre latch, swept-collision cases) are still unreachable from lookup_cookbook — worth a follow-up, since that's where the richest mechanism material lives.

`lookup_cookbook` had no reachable mechanism content. Queries for "assembly
with parts connectors and mates", "hinge", "revolute joint" and "how do I
declare a connector" all returned single-body geometry snippets — the top hit
for the first was a snippet about mirroring a symmetric part.

That gap has a cost beyond discoverability. A connector origin MUST use the
tagged `{ kind: 'vec3', value: [x, y, z] }` form; a bare `[x, y, z]` array
crashes the evaluator with an unhandled `Cannot read properties of undefined
(reading 'kind')` rather than a validation diagnostic. That tagged form
appears in no tool documentation, so the only way to discover it was to read
cookbook source the discovery tool could not reach.

Add two snippets to the indexed corpus — a two-link arm (connector + revolute
mate) and a clamshell hinge — plus the assembly/connector/mate/revolute/hinge/
joint tags, and a test asserting all four queries return a mechanism snippet
and that the returned body shows the tagged origin form.

Verified:
- Both snippets EXECUTE clean against the live engine: ok: true, 2 parts,
  zero diagnostics. A cookbook snippet that does not run is worse than none.
- Negative control: with the two snippets removed, all 5 tests fail; restored,
  all 5 pass.
- src/agent in a checkout with generated assets: 362 passed, 0 failed.
- tsc --noEmit clean.

Known limitation: this indexes the root `cookbook/` corpus. The worked
examples under `src/agent/skills/kernelcad-kinematic/cookbook/*.kcad.ts`
(scissor jack, over-centre latch, swept-collision cases) remain unreachable
from `lookup_cookbook` and are a separate follow-up.
@w1ne
w1ne enabled auto-merge August 25, 2026 20:24
…pets

`cookbook:build` generates the snippet table in kernelcad-authoring/SKILL.md
and CI drift-gates it, so adding snippets without regenerating fails
build-and-checks. Regenerated, not hand-edited.
@w1ne
w1ne merged commit 10bd88a into develop Aug 25, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant