Documentation site and CI workflows

An mdBook under docs/book: a user guide (getting started, UI tour, sketching, features,
parameters, components and joints, sheet metal, plastic, files, shortcuts, MCP) and a developer
guide (CONTRIBUTING, architecture, command engine, kernel boundary, persistent naming, test
harnesses, and the existing docs/*.md pages). `cargo xtask book` generates the command reference
from `solvecraft-cli commands` and renders the screenshots with `solvecraft-cli snapshot`, then
runs mdbook. .github/workflows/pages.yml publishes the book at /solvecraft/ and the web app at
/solvecraft/app/ (skipped while the repository is private). .github/workflows/ci.yml runs
`cargo xtask ci` on pull requests. README and Help → Documentation link to the book.

Fixes #28
Fixes #8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bherbruckandClaude Opus 5.5 committed 2026-10-09 13:25:38 +00:00
1 parent 2c3fec087e
commit 0d7e456bc1
35 files changed
+792 -5

No files matched your search

+37
View File
@@ -0,0 +1,37 @@
# The kernel boundary and truck
`crates/kernel` is SolveCraft's B-rep kernel. It wraps
[truck](https://github.com/ricosjp/truck) (Apache-2.0) for topology, NURBS geometry, booleans,
tessellation and STEP parsing, and it is the only crate allowed to use truck. Callers get
SolveCraft types (`Body`, face and edge indices, meshes, measures) and a
`KernelError` instead of truck types and panics.
## `guard`
truck can panic on geometry it doesn't handle. Every call into it goes through
`solvecraft_kernel::guard`, which catches the panic and turns it into
`KernelError::Internal`, leaving the model unchanged:
```rust
pub fn guard<T>(what: &str, f: impl FnOnce() -> Result<T>) -> Result<T>
```
A failing feature shows an error on the timeline; it never takes the app down.
## What is our own
truck has no fillets, chamfers, shells or face edits, so these are SolveCraft code in the
kernel: constant, chord and variable-radius fillets with corner blends, chamfers, shell and
offset, Delete Face, Split Face, Replace Face, sewing, STEP and IGES reading and writing beyond
truck's parser, and face provenance (which input face each output face came from, for
[persistent naming](naming.md)).
## Vendored truck crates
Patched copies of `truck-shapeops`, `truck-stepio` and `truck-meshalgo` live in `vendor/`,
wired in with `[patch.crates-io]`. The patches fix robustness bugs found by our tests and the
STEP corpus. `vendor/` is excluded from our fmt and clippy rules, and each patch should go
upstream when it can.
Some truck assertions only run in debug builds and can fail on valid geometry, so tests and CI
run with `--release`.