feat(cookbook): index mechanism/assembly snippets for lookup_cookbook - #688
Merged
Conversation
`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
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The gap (KC-10)
lookup_cookbookhad 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:The cost is bigger than discoverability. A connector origin must use the tagged form:
A bare
[x, y, z]array instead crashes the evaluator with an unhandledCannot 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 thatlookup_cookbookcould 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
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.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, sofetchPart/findPart/listPartCategories/listPartFamiliesfail there for that reason alone. They pass in a normal checkout.Known limitation
This indexes the root
cookbook/corpus. The worked examples undersrc/agent/skills/kernelcad-kinematic/cookbook/*.kcad.ts(scissor jack, over-centre latch, swept-collision cases) are still unreachable fromlookup_cookbook— worth a follow-up, since that's where the richest mechanism material lives.