bevel-cad 0.1.0__tar.gz

bevel_cad-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+**/renders/*
+!**/renders/.gitkeep
+bevel.local.yaml
+.pytest_cache/
+.ruff_cache/
+src/bevel_cad/_version.py

bevel_cad-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-14
+
+### Added
+
+- Render pipeline: `build(cfg)` to a timestamped bundle with STL / STEP / 3MF / GLB / GLTF / OBJ
+  exports, preview PNG, config snapshot, stats CSV, and log.
+- Layered OmegaConf configuration (`bevel.yaml`, `bevel.local.yaml`, `configs/<part>.yaml`,
+  `-c FILE`, `KEY=VALUE` overrides) with typed `project` / `rendering` / `viewer` blocks.
+- CLI: `render`, `config`, `list`, `describe`, `renders`, `show`, `inspect`, `upload`, `create`,
+  `add`, `templates`, `skills`, `mcp`.
+- MCP server (`bevel mcp`) exposing the CLI to AI agents; bundled agent skills.
+- Project scaffolding templates (`basic`, `label`) and a self-contained `examples/` project.
+- Entry points `bevel_cad.parts` / `bevel_cad.providers` for third-party part registries.
+
+### Changed
+
+- `requires-python` is now `>=3.11,<3.13` and `cadquery>=2.8` (the code uses
+  `cadquery.func.fillet2D`, which first shipped in 2.8; 2.8 needs Python 3.11).
+- The `viewer` extra is removed until `cadquery-web-viewer` 2.2 is published; the current
+  2.1.x release pins an OCP version that cannot coexist with cadquery 2.8.
+
+### CI / packaging
+
+- Version is derived from git tags via hatch-vcs; `bevel --version` reports it.
+- GitHub Actions: build + `twine check`, test matrix (Linux 3.11/3.12, macOS 3.12, Windows 3.12),
+  ruff, pyright, clean-environment wheel smoke test, weekly CodeQL, Dependabot, Renovate.
+- Releases publish to PyPI with Trusted Publishing (PEP 740 attestations) and attach a
+  GitHub build-provenance attestation plus the wheel and sdist to the GitHub Release.
+
+[Unreleased]: https://github.com/jimcortez/bevel-cad/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jimcortez/bevel-cad/releases/tag/v0.1.0

bevel_cad-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim Cortez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bevel_cad-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: bevel-cad
+Version: 0.1.0
+Summary: Render, export, and configure CadQuery parts: layered YAML config, timestamped render bundles, previews, web viewer, CLI and MCP server.
+Project-URL: Homepage, https://github.com/jimcortez/bevel-cad
+Project-URL: Repository, https://github.com/jimcortez/bevel-cad
+Project-URL: Issues, https://github.com/jimcortez/bevel-cad/issues
+Project-URL: Changelog, https://github.com/jimcortez/bevel-cad/blob/main/CHANGELOG.md
+Author-email: Jim Cortez <jim@jimcortez.com>
+License: MIT
+License-File: LICENSE
+Keywords: 3d-printing,cad,cadquery,mcp,step,stl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: <3.13,>=3.11
+Requires-Dist: cadquery>=2.8
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: numpy>=1.26
+Requires-Dist: omegaconf>=2.3
+Requires-Dist: pillow>=10
+Requires-Dist: pyrender>=0.1.45
+Requires-Dist: pyyaml>=6
+Requires-Dist: trimesh>=4.0
+Provides-Extra: dev
+Requires-Dist: mcp[cli]<3,>=2; extra == 'dev'
+Requires-Dist: pyright>=1.1.409; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# bevel-cad
+
+[![PyPI](https://img.shields.io/pypi/v/bevel-cad.svg)](https://pypi.org/project/bevel-cad/)
+[![Python](https://img.shields.io/pypi/pyversions/bevel-cad.svg)](https://pypi.org/project/bevel-cad/)
+[![License](https://img.shields.io/pypi/l/bevel-cad.svg)](LICENSE)
+[![CI](https://github.com/jimcortez/bevel-cad/actions/workflows/ci.yml/badge.svg)](https://github.com/jimcortez/bevel-cad/actions/workflows/ci.yml)
+
+*WARNING: project under active development and not stable at all*
+
+Render, export, and configure [CadQuery](https://cadquery.readthedocs.io/) parts.
+
+`bevel` turns a `build(cfg)` function into a **render bundle** — a timestamped folder with
+STL / STEP / 3MF / GLB / GLTF / OBJ exports, a preview PNG, the exact config that produced
+it, timings, and a log — and can push the geometry to
+[cadquery-web-viewer](https://github.com/jimcortez/cadquery-web-viewer). Configuration is
+layered YAML (OmegaConf) with `key.path=value` overrides; a project is a `bevel.yaml` plus
+`configs/` and `src/` folders; everything is available as a CLI, a Python API, and an MCP
+server so AI assistants can drive it.
+
+```bash
+pip install "bevel-cad[mcp]"               # or: uv add "bevel-cad[mcp]"
+
+bevel create my_block --template basic     # scaffold a project (interactive if args omitted)
+cd my_block
+bevel render my_block                      # -> renders/my_block_<YYYYMMDD-HHMMSS>/
+bevel render my_block my_block.cylinder_depth=null --skip preview   # override + faster loop
+bevel inspect renders/*/my_block_*.stl     # watertight? components? open edges?
+bevel render my_block --viewer             # push to a running cadquery-web-viewer
+bevel mcp                                  # expose all of the above to an AI agent
+```
+
+## A part
+
+```python
+import cadquery as cq
+import bevel_cad
+
+@bevel_cad.part(defaults={"widget": {"width": 40.0, "hole_d": 6.0}})
+def build(cfg) -> cq.Workplane:
+    p = cfg.widget
+    return cq.Workplane("XY").box(p.width, p.width, 5).faces(">Z").workplane().hole(p.hole_d)
+```
+
+Return an `Assembly` with named children to get one STL per body (and per-body colours in
+the viewer). Anything with `.wrapped` (build123d) or a `trimesh.Trimesh` works too.
+
+## Python API
+
+```python
+from bevel_cad import load_config, render_part
+
+cfg = load_config(files=["configs/widget.yaml"], dotlist=["widget.hole_d=8"])
+result = render_part(build(cfg), cfg, name="widget-8mm")
+print(result.bundle_dir, result.path_for("stl"), result.extra_paths)
+```
+
+## Project layout
+
+```
+bevel.yaml            project config: how to render (formats, tolerances, viewer)
+bevel.local.yaml      personal overrides (git-ignored)
+configs/<part>.yaml   per-part config: `part:` + the part's block
+src/<part>.py         build(cfg) -> geometry
+renders/<slug>_<ts>/  bundles
+```
+
+Config layers, low to high: built-in defaults → `~/.config/bevel/config.yaml` →
+`bevel.yaml` → `bevel.local.yaml` → part `defaults=` → `-c FILE …` → `KEY=VALUE`.
+The `project`, `rendering`, and `viewer` blocks are typed and validated; everything else is
+free-form. Missing keys raise (no silent `None`); use `cfg.get("key", default)` for optional ones.
+
+## Commands
+
+| command | |
+|---|---|
+| `bevel render [TARGET] [-c FILE]… [KEY=VALUE]… [--name N] [--out DIR] [--only F] [--skip F] [--viewer]` | build + bundle |
+| `bevel config [TARGET] …` | print the merged config |
+| `bevel list` / `bevel describe NAME` | discoverable parts and their defaults |
+| `bevel renders` / `bevel show BUNDLE` | previous bundles; files, snapshot, stats, log |
+| `bevel inspect MESH…` | watertight, components, boundary/non-manifold edges, volume |
+| `bevel upload BUNDLE` | re-push a bundle to the viewer |
+| `bevel create` / `bevel add` / `bevel templates` | scaffolding (`basic`, `label`) |
+| `bevel skills list\|install` | agent skills for building/verifying parts |
+| `bevel mcp [--transport stdio\|streamable-http]` | MCP server |
+
+Every command takes `--root DIR` and `--json`. `TARGET` is a `.py`/`.yaml` path, a project part
+name, `pkg.module[:fn]`, or a registered name (`bevel_cad.parts` / `bevel_cad.providers` entry points).
+A ready-made project lives in [examples/](examples/).
+
+## Docs
+
+[docs/config.md](docs/config.md) · [docs/cli.md](docs/cli.md) · [docs/parts.md](docs/parts.md) ·
+[docs/project-layout.md](docs/project-layout.md) · [docs/viewer.md](docs/viewer.md) ·
+[docs/mcp.md](docs/mcp.md) · [docs/skills.md](docs/skills.md) ·
+[docs/releasing.md](docs/releasing.md)
+
+## Extending
+
+Other packages register parts via entry points and can add typed config blocks / CLI flags:
+
+```toml
+[project.entry-points."bevel_cad.parts"]
+clamp = "mypkg.parts.clamp"
+[project.entry-points."bevel_cad.providers"]
+mypkg = "mypkg.registry:bevel_parts"      # -> {name: "module.path", ...}
+```
+
+```python
+from bevel_cad.cli import CliHooks, main
+main(hooks=CliHooks(schema=MySchema, add_render_flags=add_my_flags, prepare_config=wrap_cfg))
+```
+
+MIT licensed. Python 3.11–3.12 (cadquery 2.8 needs 3.11; the viewer pins `<3.13`).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev loop and [docs/releasing.md](docs/releasing.md) for releases.

bevel_cad-0.1.0/README.md

@@ -0,0 +1,114 @@
+# bevel-cad
+
+[![PyPI](https://img.shields.io/pypi/v/bevel-cad.svg)](https://pypi.org/project/bevel-cad/)
+[![Python](https://img.shields.io/pypi/pyversions/bevel-cad.svg)](https://pypi.org/project/bevel-cad/)
+[![License](https://img.shields.io/pypi/l/bevel-cad.svg)](LICENSE)
+[![CI](https://github.com/jimcortez/bevel-cad/actions/workflows/ci.yml/badge.svg)](https://github.com/jimcortez/bevel-cad/actions/workflows/ci.yml)
+
+*WARNING: project under active development and not stable at all*
+
+Render, export, and configure [CadQuery](https://cadquery.readthedocs.io/) parts.
+
+`bevel` turns a `build(cfg)` function into a **render bundle** — a timestamped folder with
+STL / STEP / 3MF / GLB / GLTF / OBJ exports, a preview PNG, the exact config that produced
+it, timings, and a log — and can push the geometry to
+[cadquery-web-viewer](https://github.com/jimcortez/cadquery-web-viewer). Configuration is
+layered YAML (OmegaConf) with `key.path=value` overrides; a project is a `bevel.yaml` plus
+`configs/` and `src/` folders; everything is available as a CLI, a Python API, and an MCP
+server so AI assistants can drive it.
+
+```bash
+pip install "bevel-cad[mcp]"               # or: uv add "bevel-cad[mcp]"
+
+bevel create my_block --template basic     # scaffold a project (interactive if args omitted)
+cd my_block
+bevel render my_block                      # -> renders/my_block_<YYYYMMDD-HHMMSS>/
+bevel render my_block my_block.cylinder_depth=null --skip preview   # override + faster loop
+bevel inspect renders/*/my_block_*.stl     # watertight? components? open edges?
+bevel render my_block --viewer             # push to a running cadquery-web-viewer
+bevel mcp                                  # expose all of the above to an AI agent
+```
+
+## A part
+
+```python
+import cadquery as cq
+import bevel_cad
+
+@bevel_cad.part(defaults={"widget": {"width": 40.0, "hole_d": 6.0}})
+def build(cfg) -> cq.Workplane:
+    p = cfg.widget
+    return cq.Workplane("XY").box(p.width, p.width, 5).faces(">Z").workplane().hole(p.hole_d)
+```
+
+Return an `Assembly` with named children to get one STL per body (and per-body colours in
+the viewer). Anything with `.wrapped` (build123d) or a `trimesh.Trimesh` works too.
+
+## Python API
+
+```python
+from bevel_cad import load_config, render_part
+
+cfg = load_config(files=["configs/widget.yaml"], dotlist=["widget.hole_d=8"])
+result = render_part(build(cfg), cfg, name="widget-8mm")
+print(result.bundle_dir, result.path_for("stl"), result.extra_paths)
+```
+
+## Project layout
+
+```
+bevel.yaml            project config: how to render (formats, tolerances, viewer)
+bevel.local.yaml      personal overrides (git-ignored)
+configs/<part>.yaml   per-part config: `part:` + the part's block
+src/<part>.py         build(cfg) -> geometry
+renders/<slug>_<ts>/  bundles
+```
+
+Config layers, low to high: built-in defaults → `~/.config/bevel/config.yaml` →
+`bevel.yaml` → `bevel.local.yaml` → part `defaults=` → `-c FILE …` → `KEY=VALUE`.
+The `project`, `rendering`, and `viewer` blocks are typed and validated; everything else is
+free-form. Missing keys raise (no silent `None`); use `cfg.get("key", default)` for optional ones.
+
+## Commands
+
+| command | |
+|---|---|
+| `bevel render [TARGET] [-c FILE]… [KEY=VALUE]… [--name N] [--out DIR] [--only F] [--skip F] [--viewer]` | build + bundle |
+| `bevel config [TARGET] …` | print the merged config |
+| `bevel list` / `bevel describe NAME` | discoverable parts and their defaults |
+| `bevel renders` / `bevel show BUNDLE` | previous bundles; files, snapshot, stats, log |
+| `bevel inspect MESH…` | watertight, components, boundary/non-manifold edges, volume |
+| `bevel upload BUNDLE` | re-push a bundle to the viewer |
+| `bevel create` / `bevel add` / `bevel templates` | scaffolding (`basic`, `label`) |
+| `bevel skills list\|install` | agent skills for building/verifying parts |
+| `bevel mcp [--transport stdio\|streamable-http]` | MCP server |
+
+Every command takes `--root DIR` and `--json`. `TARGET` is a `.py`/`.yaml` path, a project part
+name, `pkg.module[:fn]`, or a registered name (`bevel_cad.parts` / `bevel_cad.providers` entry points).
+A ready-made project lives in [examples/](examples/).
+
+## Docs
+
+[docs/config.md](docs/config.md) · [docs/cli.md](docs/cli.md) · [docs/parts.md](docs/parts.md) ·
+[docs/project-layout.md](docs/project-layout.md) · [docs/viewer.md](docs/viewer.md) ·
+[docs/mcp.md](docs/mcp.md) · [docs/skills.md](docs/skills.md) ·
+[docs/releasing.md](docs/releasing.md)
+
+## Extending
+
+Other packages register parts via entry points and can add typed config blocks / CLI flags:
+
+```toml
+[project.entry-points."bevel_cad.parts"]
+clamp = "mypkg.parts.clamp"
+[project.entry-points."bevel_cad.providers"]
+mypkg = "mypkg.registry:bevel_parts"      # -> {name: "module.path", ...}
+```
+
+```python
+from bevel_cad.cli import CliHooks, main
+main(hooks=CliHooks(schema=MySchema, add_render_flags=add_my_flags, prepare_config=wrap_cfg))
+```
+
+MIT licensed. Python 3.11–3.12 (cadquery 2.8 needs 3.11; the viewer pins `<3.13`).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev loop and [docs/releasing.md](docs/releasing.md) for releases.

bevel_cad-0.1.0/docs/cli.md

@@ -0,0 +1,37 @@
+# CLI
+
+All commands accept `--root DIR` (project root; default: nearest `bevel.yaml`), `--json`, `-v`.
+Exit codes: `0` ok, `1` user-facing failure (unknown part, invalid config, viewer down,
+export error), `2` usage.
+
+```
+bevel render [TARGET] [KEY=VALUE]... [-c FILE]... [--name N] [--out DIR]
+             [--only FMT[,FMT]] [--skip FMT[,FMT]] [--viewer | --no-viewer]
+bevel config [TARGET] [KEY=VALUE]... [-c FILE]...
+bevel upload BUNDLE [KEY=VALUE]... [-c FILE]... [--name N]
+bevel list                       bevel describe NAME [--source]
+bevel renders [--limit N]        bevel show BUNDLE
+bevel inspect MESH...            bevel project
+bevel create [NAME] [--description D] [--format stl|step|3mf|glb] [--template basic|label]
+             [--dir PATH] [--param KEY=VALUE] [-y] [--no-skills] [--force]
+bevel add NAME [--template T] [--param KEY=VALUE] [-y] [--force]
+bevel templates                  bevel skills list|install|path [--project|--user|--to DIR] [--force]
+bevel mcp [--transport stdio|streamable-http] [--host H] [--port P]
+```
+
+## TARGET resolution
+
+1. an existing `.py` file, or a `.yaml` file (used as the last config layer; its `part:` key names the code);
+2. `<configs_dir>/<name>.yaml` (+ `part:`), then `<src_dir>/<name>.py` in the project;
+3. `package.module[:callable]`;
+4. a registered name (`bevel_cad.parts` / `bevel_cad.providers` entry points, bundled examples).
+
+Positionals after the target that contain `=` are dotlist overrides.
+
+`--only` enables exactly the listed formats (plus `config` and `stats`); `--skip` disables the
+listed ones. Both accept format names (`stl`) or job names (`iso`).
+
+## `--json`
+
+Every command prints a JSON object/array with `--json` — the same data the MCP server returns.
+`render` gives `{run_name, stem, bundle_dir, files{job: path}, extra_files[], viewer_names[], stats{}}`.

bevel_cad-0.1.0/docs/config.md

@@ -0,0 +1,92 @@
+# Configuration
+
+bevel uses [OmegaConf](https://omegaconf.readthedocs.io/) to merge YAML layers into one
+config object with attribute access (`cfg.rendering.exports.stl.enabled`).
+
+## Layers (low → high precedence)
+
+| # | layer | where |
+|---|---|---|
+| 1 | built-in defaults | `bevel_cad/config/defaults.yaml` |
+| 2 | user | `$XDG_CONFIG_HOME/bevel/config.yaml` (`~/.config/bevel/config.yaml`) |
+| 3 | project | `bevel.yaml`, found by walking up from cwd (`$BEVEL_ROOT` / `--root` override) |
+| 4 | project local | `bevel.local.yaml` next to it (git-ignored) |
+| 5 | part defaults | `@bevel_cad.part(defaults=...)` |
+| 6 | `-c FILE …` | in the order given; a `.yaml` render target or `configs/<name>.yaml` is appended here |
+| 7 | CLI dotlist | `key.path=value` (values parsed as YAML: `true`, `null`, `3.5`, `[a,b]`) |
+| 8 | programmatic | `load_layers(overrides=...)` |
+
+`bevel config [TARGET]` prints the merged result; `<stem>.yaml` in every bundle is the
+snapshot that produced that render (re-run with `bevel render -c <stem>.yaml`).
+
+## Typed blocks
+
+```yaml
+project:
+  name: my_project
+  description: ...
+  configs_dir: configs      # or a list
+  src_dir: src
+
+rendering:
+  name: null                # run name; falls back to the part name
+  output_dir: renders       # relative to the project root (cwd without a project)
+  tolerance: 0.001          # tessellation (mm)
+  angular_tolerance: 0.05
+  exports:                  # mapping keyed by job name
+    stl:     {enabled: true, stl_ascii: false}
+    step:    {enabled: false, write_pcurves: true, precision_mode: 0}
+    "3mf":   {enabled: false}
+    glb:     {enabled: true}
+    gltf:    {enabled: false}
+    obj:     {enabled: false, unit_scale_mm_to_m: true, target_face_count: null, watertight_required: false}
+    preview: {enabled: true, image_width: 800, image_height: 600, elevation: 30, azimuth: 45, roll: 0,
+              light_azimuth: 225, light_elevation: 45, color: "#b3b3b3", background: "#1a1a2e", opacity: 1.0}
+    config:  {enabled: true}
+    stats:   {enabled: true}
+    iso:     {format: preview, filename: "{name}-iso.png", azimuth: 135}   # extra jobs: any name
+
+viewer:
+  enabled: false            # or --viewer
+  host: localhost
+  port: 32323
+  upload_timeout: 300.0
+  post_timeout: 60.0
+  tolerance: 0.05           # coarser tessellation for the viewer
+  angular_tolerance: 0.1
+  style: {protocol: null, texture: null, color_faces: null, color_edges: null, color_vertices: null}
+```
+
+Export jobs: `format` defaults to the key, `filename` to `{name}.<ext>` where `{name}` is the
+bundle stem and `{run_name}` the raw run name. Jobs run in a fixed order
+(step, stl, 3mf, glb, gltf, obj, preview, config, stats); `preview`/`obj`/`gltf` synthesise a
+disabled GLB job when GLB is off. Two jobs resolving to the same file is an error.
+
+Typed blocks reject unknown keys and wrong types (`viewer.port=abc` fails at load). All other
+top-level keys are free-form for parts. The merged config is **struct**: a missing attribute
+raises `ConfigAttributeError` (an `AttributeError`) instead of returning `None`; use
+`cfg.get("key", default)`.
+
+## Extending with a schema
+
+```python
+from dataclasses import dataclass, field
+from bevel_cad import BevelSchema
+
+@dataclass
+class Bounds: width: float = 100.0; height: float = 100.0
+
+@dataclass
+class MySchema(BevelSchema):
+    output_bounds: Bounds = field(default_factory=Bounds)
+
+cfg = load_config(schema=MySchema, files=["configs/x.yaml"])
+```
+
+Validation in `__post_init__` runs when you call `OmegaConf.to_object(cfg.output_bounds)`.
+
+## Legacy shapes
+
+A `server:` block (`server.viewer.host`, `server.color_faces`, …) and list-form
+`rendering.exports` (`- format: stl`) are converted on load with a `DeprecationWarning`, so
+older snapshots stay usable.

bevel_cad-0.1.0/docs/mcp.md

@@ -0,0 +1,36 @@
+# MCP server
+
+`bevel mcp` exposes every command as typed MCP tools (official `mcp` Python SDK v2).
+
+```bash
+pip install "bevel-cad[mcp]"
+bevel mcp --root /path/to/project                       # stdio (Claude Code / Desktop)
+bevel mcp --transport streamable-http --port 8765       # HTTP
+uv run mcp dev src/bevel_cad/mcp/server.py              # MCP Inspector
+```
+
+Claude Code:
+
+```bash
+claude mcp add bevel -- uv run --directory /path/to/project bevel mcp --root .
+```
+
+## Tools
+
+`project_info`, `list_parts`, `describe_part(name)`, `read_part_source(name)`,
+`resolve_config(target, configs, overrides)`, `render(target, configs, overrides, name, only,
+skip, viewer, out)`, `get_preview(bundle)` → image, `inspect_mesh(path)`, `list_renders(limit)`,
+`describe_render(bundle)`, `upload(bundle, name)`, `list_templates`, `create_project(...)`,
+`add_part(...)`, `list_skills`, `read_skill(name)`.
+
+`render` runs in a subprocess (`bevel render --json`), so OCC crashes cannot take the server
+down; log lines are forwarded as progress. Results are the same JSON the CLI prints with `--json`.
+
+## Resources
+
+`bevel://project`, `bevel://parts/{name}`, `bevel://renders/{stem}/config|stats|log`,
+`bevel://skills/{name}`.
+
+## Prompts
+
+`build_part`, `verify_render`, `iterate_model` return the matching skill text.

bevel_cad-0.1.0/docs/parts.md

@@ -0,0 +1,39 @@
+# Parts
+
+A part is a module exposing `build(cfg)` that **returns** geometry. See the bundled
+skill `bevel-part-authoring` (`bevel skills path`) for the full guide and pitfalls.
+
+```python
+import bevel_cad
+
+@bevel_cad.part(name=None, defaults={...}, schema=None, description="...")
+def build(cfg): ...
+```
+
+- `defaults` — merged as the *part* config layer (below `-c` files and CLI overrides).
+- `schema` — optional dataclass extending `BevelSchema` for strict validation of your blocks.
+- Accepted return types: `cq.Assembly` (named children → per-body STLs and viewer colours),
+  `cq.Shape`, `cq.Workplane`, `trimesh.Trimesh`, anything with `.wrapped`.
+- Returning `None` means "the part rendered itself" (legacy contract); nothing is written.
+
+## Discovery
+
+`bevel list` shows, in precedence order: project `src/` files, `bevel_cad.parts` entry points,
+`bevel_cad.providers` (a callable returning `{name: "module.path"}`), bundled examples.
+
+Standalone files are imported with their directory on `sys.path`, so sibling imports work.
+
+## Example project
+
+`examples/` in the bevel-cad repo is a self-contained bevel project (`bevel.yaml`, `configs/`,
+`src/`, `renders/`) with `button_label` (engraved plate with a button hole, two bodies) and
+`spacer_washer` (inch-dimensioned filleted washer):
+
+```bash
+cd examples
+bevel list
+bevel render button_label_custom          # configs/button_label_custom.yaml -> src/button_label.py
+bevel render spacer_washer spacer_washer.outer_diameter_in=2.0
+```
+
+Copy the folder anywhere; nothing in it depends on being inside the repository.

bevel_cad-0.1.0/docs/project-layout.md

@@ -0,0 +1,19 @@
+# Project layout
+
+```
+my_project/
+  bevel.yaml            project config (typed blocks project/rendering/viewer + anything shared)
+  bevel.local.yaml      personal overrides, git-ignored
+  configs/<part>.yaml   per-part: `part: <source>` + the part's own block
+  src/<part>.py         part sources (src/ is put on sys.path)
+  renders/<slug>_<YYYYMMDD-HHMMSS>/
+      <stem>.stl  <stem>_<body>.stl  <stem>.glb  <stem>.png  <stem>.yaml  <stem>.csv  <stem>.log
+      [<stem>.step  <stem>.3mf  <stem>.gltf  <stem>.obj]
+  .claude/skills/bevel-*/   agent skills (bevel skills install --project)
+```
+
+- Root discovery: walk up from cwd for `bevel.yaml`; `$BEVEL_ROOT` or `--root` override.
+- `project.configs_dir` may be a list (e.g. `[knot_configs, part_configs]`).
+- `rendering.output_dir` resolves against the root (against cwd when there is no project).
+- `bevel create NAME` scaffolds all of this plus a first part from a template;
+  `bevel add NAME` adds another config/source pair.

bevel_cad-0.1.0/docs/releasing.md

@@ -0,0 +1,99 @@
+# Releasing bevel-cad
+
+Releases are fully automated from a git tag. No API tokens or secrets are stored in the
+repository or in GitHub: PyPI publishing and artifact signing use GitHub's OIDC identity
+("Trusted Publishing").
+
+## One-time setup
+
+Do these once, in order. Nothing here is a secret; there is nothing to paste into GitHub.
+
+### 1. PyPI: add a *pending* trusted publisher
+
+`bevel-cad` does not exist on PyPI yet, so the publisher must be registered as *pending*
+(it becomes a normal publisher on the first upload, which also creates the project).
+
+1. Log in at <https://pypi.org>, verify your email and enable 2FA if not already done.
+2. Go to **Your account → Publishing** (<https://pypi.org/manage/account/publishing/>).
+3. Under **Add a new pending publisher → GitHub**, enter exactly:
+
+   | Field | Value |
+   |---|---|
+   | PyPI project name | `bevel-cad` |
+   | Owner | `jimcortez` |
+   | Repository name | `bevel-cad` |
+   | Workflow name | `release.yml` |
+   | Environment name | `pypi` |
+
+   The environment name must match; the workflow declares `environment: pypi`.
+
+### 2. GitHub: create the `pypi` environment
+
+1. Repo **Settings → Environments → New environment**, name it `pypi`.
+2. Under **Deployment branches and tags** choose **Selected branches and tags** and add a
+   tag rule `v*`. This stops any non-tag workflow from ever obtaining the publishing identity.
+3. Optional: add yourself as a **Required reviewer** for a manual approval gate before each
+   PyPI upload. The workflow will pause at the `publish` job until approved.
+
+### 3. GitHub: Actions and security settings
+
+- **Settings → Actions → General → Workflow permissions** can stay at *Read repository contents
+  and packages permissions*. Each job escalates only what it needs (`contents: write`,
+  `id-token: write`, `attestations: write` on the publish job).
+- **Settings → Code security**: enable *Dependabot alerts* and *Dependabot security updates*.
+  Do **not** enable CodeQL *Default setup*; the repo runs CodeQL through
+  `.github/workflows/codeql.yml` (advanced setup) and the two conflict.
+
+### 4. Renovate
+
+Install the Mend Renovate GitHub App on the `jimcortez/bevel-cad` repository from
+<https://github.com/apps/renovate>. Configuration lives in `.github/renovate.json5`
+(weekend schedule, branch automerge, lock-file maintenance). Dependabot handles GitHub Actions.
+
+### 5. Local `gh` CLI
+
+`gh auth login -h github.com` on the machine you release from, so you can watch runs
+(`gh run watch`) and verify attestations (`gh attestation verify`).
+
+## Cutting a release
+
+1. Make sure `main` is green in CI and `CHANGELOG.md` has the version's entry with a date.
+2. Tag the commit on `main` and push the tag:
+
+   ```bash
+   git switch main && git pull
+   git tag -a v0.1.0 -m "v0.1.0"
+   git push origin v0.1.0
+   ```
+
+3. `release.yml` then:
+   - checks the tag is a valid PEP 440 version and is reachable from `main`;
+   - re-runs the full build + test matrix + clean-install smoke test on the tagged commit;
+   - signs a build-provenance attestation for the wheel and sdist;
+   - publishes to PyPI with PEP 740 attestations;
+   - creates a GitHub Release with auto-generated notes and attaches the wheel and sdist.
+
+The package version comes from the tag (hatch-vcs). `v0.1.0` → `bevel-cad 0.1.0`. Untagged
+builds are `0.1.1.devN`. There is no version string to bump in the tree.
+
+## Verifying a release
+
+```bash
+# Provenance attestation stored on GitHub
+gh attestation verify bevel_cad-0.1.0-py3-none-any.whl --owner jimcortez
+
+# PyPI attestation and a clean install
+uv venv /tmp/bevel-check && VIRTUAL_ENV=/tmp/bevel-check uv pip install bevel-cad==0.1.0
+/tmp/bevel-check/bin/bevel --version
+```
+
+The PyPI project page shows "Verified details" with the publishing workflow and commit.
+
+## If a release fails
+
+- `check-tag` fails: the tag is not on `main` or is not PEP 440. Delete and re-tag.
+- `build` fails: fix on `main`, then move the tag (`git tag -f`, `git push -f origin v0.1.0`)
+  only if nothing was published yet. Once PyPI has the version, cut a new patch version instead;
+  PyPI file names can never be reused.
+- `publish` fails at PyPI with an OIDC error: re-check the trusted publisher fields above
+  (repository, workflow file name and environment must match exactly).