docs(skills): add engineering skill library under .claude/skills (#1023)

## What

Eighteen skills under `.claude/skills/`, each capturing the method and
traps for one recurring class of work, so engineers and smaller models
can debug, extend, validate, benchmark, and ship this kernel without
prior project context. `README.md` indexes them with a suggested reading
order and a glossary.

**Doctrine and verification:** `debugging-doctrine`,
`solid-verification`, `numerical-robustness`, `testing`.
**Engine internals:** `boolean-debugging`, `analytic-preservation`,
`tessellation`, `fillet-blend`.
**Building:** `layer-boundaries`, `add-operation`, `wasm-bindings`,
`render-verify`, `io-formats`.
**Shipping:** `pr-workflow`, `profiling`, `parity-benchmarking`,
`release-flow`.
**Work selection:** `roadmap`, a living index of open, deferred, and
terminal cases with the chase filters and the acceptance bar.

## How it was built

Each skill went through research, authoring, adversarial verification,
and fix stages, then cross-skill consistency and coverage passes. Every
file path, symbol, and command was checked against the current tree.
Several beliefs carried in from earlier work were found stale and
corrected in place (tooling that now exists, a heal function that is
implemented rather than a stub, a deprecation already removed).

## Scope

Documentation only. No source, test, or build changes. The `roadmap`
skill declares a maintenance contract: sessions that close, defer, or
discover a work item update it in the same PR.

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds the brepkit engineering skill library under `.claude/skills` with
18 task-focused guides and references so contributors can debug, extend,
verify, benchmark, and ship the kernel. Docs-only; includes an indexed
`README.md` and a maintenance rule for the `roadmap` skill.

- **New Features**
- Eighteen skill guides across doctrine/verification, engine internals,
building, shipping, and work selection, each with `SKILL.md` +
`reference.md` verified against current symbols, paths, and commands.
  - `README.md` index with suggested reading order and glossary.
- `roadmap` adds a maintenance contract: sessions that
close/defer/discover work must update it in the same PR.

<sup>Written for commit 3f6b648.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/andymai/brepkit/pull/1023?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

Author: andymai

.claude/skills/README.md

@@ -0,0 +1,55 @@
+# brepkit Skill Library
+
+Distilled working knowledge for building, debugging, and shipping the brepkit B-Rep kernel:
+each skill captures the method and traps for one recurring class of task. Written for
+engineers and agents working in this repo (plus `~/Git/brepjs` for cross-repo work), with
+only this repo and CLAUDE.md as context.
+
+## Index
+
+| Skill | Reach for it when |
+|-------|-------------------|
+| [roadmap](roadmap/SKILL.md) | Picking work in an autonomous session: what is open, what is terminal, the chase filters, and the acceptance bar. |
+| [debugging-doctrine](debugging-doctrine/SKILL.md) | Any hard geometry bug where the first diagnosis did not hold, or before a multi-pass investigation. |
+| [solid-verification](solid-verification/SKILL.md) | Deciding whether a solid is actually correct: watertight, manifold, right volume, and whether a "passing" check proves anything. |
+| [boolean-debugging](boolean-debugging/SKILL.md) | A fuse, cut, or intersect mesh-falls-back, loses faces, gives wrong volume, fails validation, or varies across runs. |
+| [fillet-blend](fillet-blend/SKILL.md) | A fillet or chamfer leaves free edges, opens the shell, silently changes nothing, or you must decide whether the deprecated v1 fillet code is safe to touch. |
+| [analytic-preservation](analytic-preservation/SKILL.md) | An operation degrades exact analytic geometry to NURBS or a mesh, face counts explode, or you are triaging the approx census. |
+| [numerical-robustness](numerical-robustness/SKILL.md) | Results flip under tiny input nudges, seams and periodic geometry misbehave, or code compares, hashes, or buckets floats. |
+| [tessellation](tessellation/SKILL.md) | Mesh cracks at face boundaries, boundary edges or non-manifold edges appear, or you are adding a face mesher in `crates/operations/src/tessellate/`. |
+| [add-operation](add-operation/SKILL.md) | Adding or extending a modeling operation in `crates/operations`, end to end through tests and wasm exposure. |
+| [layer-boundaries](layer-boundaries/SKILL.md) | Adding a workspace dep, placing new code in a crate, adding an `EdgeCurve` or `FaceSurface` variant, or fixing a boundaries CI failure. |
+| [wasm-bindings](wasm-bindings/SKILL.md) | Adding `BrepKernel` methods, wiring `executeBatch`, building the wasm package, or debugging wasm-only failures. |
+| [io-formats](io-formats/SKILL.md) | A STEP or other file imports wrong (dropped solids, all-NURBS, hard entity errors), verifying writer round-trips, capturing a faithful fixture, or adding a format in `crates/io`. |
+| [render-verify](render-verify/SKILL.md) | Working on `brepkit-render` or visually verifying a solid, including headless capture of a live viewer window. |
+| [testing](testing/SKILL.md) | Writing or placing tests, building a faithful regression fixture, handling golden mismatches, or ending a session with unverified work. |
+| [profiling](profiling/SKILL.md) | An operation or benchmark is slow, a criterion bench misbehaves, or a PR needs before/after perf numbers. |
+| [parity-benchmarking](parity-benchmarking/SKILL.md) | Proving brepkit matches or beats the reference kernel, overlaying a local build into the gridfinity tool, or quoting any perf or parity claim. |
+| [pr-workflow](pr-workflow/SKILL.md) | Committing, pushing, opening, or merging a PR; hook failures, commitlint, the AI-review merge gate, worktrees. |
+| [release-flow](release-flow/SKILL.md) | Landing a merged brepkit change in brepjs: npm release, wasm pin bump, type sync, adapter update. |
+
+## Suggested reading order for a new engineer
+
+1. Doctrine and verification: `roadmap`, `debugging-doctrine`, `solid-verification`, `numerical-robustness`, `testing`.
+2. The engine: `boolean-debugging`, `fillet-blend`, `analytic-preservation`, `tessellation`.
+3. Building: `layer-boundaries`, `add-operation`, `wasm-bindings`, `io-formats`, `render-verify`.
+4. Shipping: `pr-workflow`, `profiling`, `parity-benchmarking`, `release-flow`.
+
+## Glossary
+
+- **GFA**: the General Fuse Algorithm, the boolean engine in `crates/algo` (`gfa.rs` is the orchestrator).
+- **PaveFiller**: the GFA intersection phase (`crates/algo/src/pave_filler/`). It finds all pairwise interferences between the operands before any faces are split.
+- **FF/EE/VF phases**: PaveFiller sub-phases, one per entity pair type: vertex-vertex, vertex-edge, edge-edge, vertex-face, edge-face, face-face. See `pave_filler/phase_*.rs`.
+- **Pave**: an intersection point on an edge, stored with its curve parameter.
+- **Pave block**: the edge segment between two consecutive paves; the unit the builder splits edges into.
+- **SD (same-domain)**: two faces (or edges) from different operands that occupy the same geometry. They must be detected and merged to one representative or booleans produce duplicates and open shells.
+- **PCurve**: the 2D curve in a face's UV parameter space that traces a 3D edge on that surface. Face splitting and classification run in UV space, so a wrong pcurve breaks them.
+- **Analytic vs NURBS**: analytic means an exact typed surface or curve (plane, cylinder, cone, sphere, torus, line, circle, ellipse). NURBS is the free-form spline representation. Keeping results analytic is brepkit's differentiator: exact downstream math, compact data, GPU meshing from parameters.
+- **Mesh fallback**: when a boolean cannot assemble a valid B-Rep, it degrades to a triangle-mesh boolean and re-imports the triangles as many small planar faces. Always a defect to investigate, never an acceptable result.
+- **Watertight**: the tessellated mesh has zero boundary edges; every triangle edge is shared by exactly two triangles.
+- **Manifold**: at the B-Rep level, every edge is used by exactly two faces with consistent orientation.
+- **Euler check**: the V - E + F consistency check in solid validation; a cheap topological invariant that catches missing or duplicated entities.
+- **Seam**: the edge where a closed surface's parameterization wraps around (u=0 meets u=2*pi on a cylinder). Seam edges appear twice in a face's UV boundary.
+- **Periodic surface**: a surface closed in one or both parameter directions (cylinder, cone, sphere, torus). Periodic wrap-around is a standing source of seam and interval bugs.
+- **Deflection**: the maximum allowed chord deviation between a mesh and the true surface; the knob that controls tessellation density.
+- **The reference kernel**: the established C++ CAD kernel brepkit benchmarks against through the brepjs harness. Parity with it, then beating it, is the project's acceptance bar; see `parity-benchmarking` for how to run the head-to-head.

.claude/skills/add-operation/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: add-operation
+description: Use when adding a new modeling operation to crates/operations (a new pub fn taking &mut Topology and returning a SolidId or similar), when extending an existing operation with a new code path, or when an operation's tests need to prove correctness before shipping. Covers implementation traps, error handling, test placement, wasm exposure, and the verification bar.
+---
+
+# Adding an Operation to brepkit
+
+## When to use
+
+You are creating or substantially extending an operation in `crates/operations/src/` (extrude/revolve/sweep class, a measure, a transform, a new primitive). CLAUDE.md Recipe 3 gives the file scaffolding. This skill adds what Recipe 3 omits: the verification bar, where tests go, and the correctness traps that produce compiles-but-wrong geometry.
+
+## Quick reference
+
+| Step | Command / API | Expect |
+|------|---------------|--------|
+| Scaffold | CLAUDE.md Recipe 3 | file, fn, `lib.rs` module, wasm binding, batch dispatch |
+| Measure | `crate::measure::solid_volume(&topo, solid, 0.001)` | relative error < 1% vs closed form |
+| Validate | `crate::validate::validate_solid(&topo, solid)` | `report.is_valid()` true |
+| Watertight | `tessellate_solid_with_tolerance` + `tessellate::is_watertight` | 0 boundary + 0 non-manifold edges (index-based); also re-check with the positional-weld helper from `tessellate_watertight.rs` |
+| Census | `cargo run --release --example approx_census -p brepkit-operations` | no new `brepkit_approx` probe fires for your op |
+| Gate | `cargo clippy --all-targets -- -D warnings && cargo fmt --all && ./scripts/check-boundaries.sh` | clean |
+
+## Procedure
+
+1. **Scaffold per CLAUDE.md Recipe 3.** Signature `pub fn op_name(topo: &mut Topology, ...) -> Result<SolidId, OperationsError>`.
+2. **Walk faces correctly.** Any solid-scoped loop over faces must use `brepkit_topology::explorer::solid_faces` (there is also `solid_edges`). See CLAUDE.md "Walking faces in a solid" for the exception rule for per-shell operations. Iterating only `outer_shell()` compiles, passes on simple boxes, and silently skips cavity faces on hollow solids.
+3. **Respect the borrow pattern and error rules.** Snapshot-then-allocate and closure return type annotations: see CLAUDE.md Common Pitfalls. The workspace denies `unwrap_used`, `panic`, and `unsafe_code` in production code; test modules opt out with `#![allow(clippy::unwrap_used, clippy::expect_used)]`.
+4. **If your op copies edges that may carry periodic curves** (`EdgeCurve::Circle` or `Ellipse`), read reference.md "Periodic edge copies" before writing the copy loop. Getting this wrong recovers the complementary arc (minor instead of major) and only reversed edges expose it.
+5. **Write tests** (placement below). Every geometry-producing op needs at least: a volume-vs-closed-form test, a `validate_solid` test, and a watertight-tessellation test.
+6. **Run the verification bar** (reference.md "Verification bar" has the exact APIs and checkpoint expectations). If the op touches analytic geometry, run the approx census; a fallback probe firing for your op means you degraded analytic surfaces to NURBS or mesh, see the analytic-preservation skill.
+7. **Expose to wasm** per CLAUDE.md Recipe 4; details in the wasm-bindings skill (binding module choice, `batch_*` companion, contract tests via `execute_batch()`).
+8. **Run the gate commands** from the quick reference before pushing.
+
+## Where tests go
+
+CLAUDE.md's Testing section reads as if golden and integration tests live at the repo root. They do not; the root dirs hold data and docs only.
+
+| Kind | Location | Pattern |
+|------|----------|---------|
+| Unit tests | `crates/operations/src/<op>/tests.rs`, declared via `mod tests;` at the bottom of `<op>.rs` | `extrude.rs` + `extrude/tests.rs` |
+| Crate integration | `crates/operations/tests/*.rs` | `tessellate_watertight.rs`, `boolean_invariants.rs`, `proptest_operations.rs` |
+| Golden | `crates/operations/tests/golden_regression.rs`, data in `tests/golden/data/` | regenerate: `UPDATE_GOLDEN=1 cargo test --workspace golden` |
+| Wasm contract | wasm crate, via `execute_batch()` only | see wasm-bindings skill |
+
+Do not add standalone test files under the root `tests/integration/` or `tests/golden/`; both READMEs there confirm tests are crate-level.
+
+## Pitfalls: what NOT to conclude
+
+| Observation | Wrong conclusion | Reality |
+|-------------|------------------|---------|
+| Volume matches closed form | Geometry is correct | Volume can read high on arc-edged results and a nearly-unmodified solid can pass. Also classify interior/exterior probe points with `crate::classify::classify_point` (ray-cast). Never trust the winding classifier for faceted or NURBS solids. |
+| Census reports exact analytic | Op is correct | It only proves no approximation fallback fired, not that the geometry is right. A wrong-but-analytic result passes the census. |
+| Mesh indices share vertices | Mesh is watertight | Watertightness is geometric: weld vertices by quantized position first, then check edge sharing. Use `tessellate::is_watertight` / `boundary_edge_count`, or copy the `boundary_edges` helper from `crates/operations/tests/tessellate_watertight.rs`. |
+| Box test passes | Face walk is complete | Boxes have no inner shells. Add a hollow-solid case (shell_op or boolean-cut cavity) if the op walks faces. |
+| Forward-edge arc test passes | Periodic edge copy is correct | Only a reversed `OrientedEdge` swaps stored vertex order vs curve parameterization. Add a reversed-half-circle test (see reference.md). |
+| Volume of an off-origin primitive is wrong | The measure is broken | Primitives place their base at z = 0, not centered. Check your expected value first. |
+| Cone surface points land off the cone | ConicalSurface is broken | `half_angle` is measured from the radial plane, not from the axis. See reference.md "Cone conventions". |
+
+## Sibling skills
+
+- **wasm-bindings**: binding module, `js_name`, input validation helpers, batch dispatch, contract tests.
+- **testing**: fixtures, proptest, golden data regeneration, test layout in depth.
+- **solid-verification**: the full verification bar in depth (measure, validate, watertight, classifiers, census).
+- **analytic-preservation**: keeping results as typed analytic surfaces instead of NURBS.
+- **layer-boundaries**: which crates your op may `use`; `./scripts/check-boundaries.sh` enforces it.
+
+## Reference
+
+Detailed APIs, checkpoints, and the periodic-edge treatment: [reference.md](reference.md).