dcad 0.1.0__tar.gz

dcad-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Prepare vendored CAD skill
+        run: bash scripts/setup-dev.sh
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -q
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Prepare vendored CAD skill
+        run: bash scripts/setup-dev.sh
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: pip install build && python -m build
+
+      - name: Smoke-test wheel install
+        run: bash scripts/test-install.sh dist/dcad-*.whl

dcad-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: PYPI_API_TOKEN
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Prepare vendored CAD skill
+        run: bash scripts/setup-dev.sh
+
+      - name: Build package
+        run: pip install build && python -m build
+
+      - name: Smoke-test wheel install
+        run: bash scripts/test-install.sh dist/dcad-*.whl
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

dcad-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+.venv-ci/
+venv/
+env/
+
+# Test / lint / type-check caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Local runtime artifacts — never commit generated CAD output or user config
+validation-snapshots/
+*.step
+*.stl
+*.3mf
+*.glb
+*.gltf
+.runs/
+.derivecad.toml
+credentials.toml
+
+# Deliberate exception: small tracked fixture files
+!tests/fixtures/*.step
+!tests/fixtures/*.stl

dcad-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## Unreleased
+
+- PyPI distribution renamed to `dcad` — install with `pipx install dcad`.
+- Milestone 1: CLI scaffold, layered config, keyring-backed secrets with file fallback,
+  `dcad init` setup wizard, sandboxed build123d subprocess execution, STEP/STL/3MF/GLB
+  export, deterministic geometry inspection, and `dcad run` wiring the fixed demo
+  bracket pipeline end-to-end. CI (lint + test) on macOS/Ubuntu.

dcad-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,138 @@
+# Contributing to dcad
+
+## Releasing
+
+The PyPI package name is **`dcad`** (users install with `pipx install dcad`).
+
+1. Bump `version` in `pyproject.toml` and `src/derive_cad/__about__.py`.
+2. Update `CHANGELOG.md`.
+3. Create a GitHub release (tag = version, e.g. `v0.1.0`).
+4. The [Publish workflow](.github/workflows/publish.yml) uploads the wheel to PyPI when the
+   release is published.
+
+Set `PYPI_API_TOKEN` in the repo's `PYPI_API_TOKEN` GitHub environment before the first release.
+
+To build and smoke-test locally:
+
+```bash
+bash scripts/publish.sh
+```
+
+To upload manually (requires `PYPI_API_TOKEN`):
+
+```bash
+PYPI_API_TOKEN=... bash scripts/publish.sh --upload
+```
+
+## Dev setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+`dcad` bundles the vendored `packages/cadpy` and `skills/cad` inside the wheel — one install
+command is enough.
+
+Run lint and tests before opening a PR:
+
+```bash
+ruff check .
+pytest -q
+```
+
+`pytest` includes a marked `integration` suite (`tests/test_cad_runner.py`,
+`tests/test_export.py`, `tests/test_render.py`) that runs the real build123d subprocess
+sandbox (and, for `test_render.py`, a real Playwright snapshot render) end-to-end. These are slower
+than the unit tests but are the ones that actually prove the CAD pipeline works — don't skip
+them locally before submitting a PR that touches `cad/`.
+
+For a PR that changes prompts (`llm/prompts.py`), upstream repair guidance
+(`skills/cad/references/repair-loop.md`), or the
+brief's validation-target schema (`llm/brief.py`, `cad/validation.py`), also run
+`python benchmarks/run_benchmarks.py` against a real configured provider — see
+`benchmarks/cases.py` and the "What we ported" section below.
+
+## Platform caveats worth knowing before touching `cad/sandbox.py`
+
+- **No musllinux/Alpine wheels** for build123d's OCP binding — anything Docker-based needs a
+  glibc base image (`python:3.12-slim`, not `-alpine`).
+- **Windows has no `resource` module** — the POSIX memory/CPU resource limits in
+  `cad/sandbox.py` are a documented gap on Windows, not silently ignored. The subprocess
+  timeout is the cross-platform backstop against runaway generation scripts.
+- **macOS's `RLIMIT_AS` frequently can't be lowered** below the process's already-mapped
+  virtual address space (dyld's shared cache alone can reserve several GB), so the memory
+  limit in `cad/sandbox.py` is applied best-effort and never blocks launching the subprocess
+  if `setrlimit` fails.
+
+## Secrets
+
+This project handles real API keys. Never commit real keys, `credentials.toml`, or any
+fixture containing a live secret. Tests exercise the secrets layer against fake/mocked
+keyring backends (see `tests/test_secrets.py`) — no real OS keychain is touched in CI.
+
+## Adding a new LLM provider
+
+Add an entry to `PROVIDERS` in `src/derive_cad/llm/providers.py` with its env var name and a
+sensible default model string. Users can already reach any litellm-supported provider via the
+"Other" option in `dcad init`, so a first-class entry here is about a smoother onboarding
+experience, not enabling something otherwise impossible.
+
+## Adding a new export format
+
+Register the format in `src/derive_cad/cad/runner.py` (`_SIDECAR_FLAGS`) if
+`skills/cad/scripts/step` supports a matching `--<format>` sidecar flag. Exports run through
+cadpy during `dcad run` via `export_sidecars()` or inline `run_script(..., sidecar_formats=...)`.
+
+## Vendored `skills/cad` and `packages/cadpy`
+
+This repo vendors the full upstream CAD skill from
+[earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad):
+
+- `skills/cad/` — `SKILL.md`, `references/*.md`, `scripts/step`, `scripts/inspect`, `scripts/snapshot`
+- `packages/cadpy/` — STEP generation, selector inspection, assemblies
+- `skills/cad/scripts/packages/cadpy` → `../../../../packages/cadpy` (symlink)
+
+Pinned upstream commit: `skills/cad/UPSTREAM_SHA`.
+
+`dcad run` orchestrates the SKILL.md 10-step workflow. Low-level tools are exposed as
+`dcad step`, `dcad inspect`, and `dcad snapshot` (passthrough to vendored scripts).
+
+Sync from upstream when needed:
+
+```bash
+git clone https://github.com/earthtojake/text-to-cad.git /tmp/text-to-cad-upstream
+cp -R /tmp/text-to-cad-upstream/skills/cad ./skills/cad
+cp -R /tmp/text-to-cad-upstream/packages/cadpy ./packages/cadpy
+ln -sf ../../../../packages/cadpy skills/cad/scripts/packages/cadpy
+```
+
+## What we ported from earthtojake/text-to-cad's skill docs
+
+That project's `skills/cad/SKILL.md` and `references/*.md` document a staged workflow:
+classify the task, write a CAD brief before coding, generate via `scripts/step`, validate
+with `scripts/inspect`, review snapshots, and repair failures per `repair-loop.md`.
+`llm/brief.py`, `cad/validation.py`, `cad/render.py`, and `llm/review.py` implement this
+against dcad's litellm-based CLI; repair prompts load the vendored `repair-loop.md` directly.
+
+**Not vendored:** `viewer/`, `skills/cad-viewer` (no embedded CAD Viewer UI). `dcad run`
+uses Playwright snapshots via `skills/cad/scripts/snapshot` for vision review; `dcad open` opens files in the OS default app.
+
+**Stretch / optional:** `skills/step-parts` purchasable-parts library (`llm/step_parts.py`
+logs when absent). Assembly codegen and repair prompts load `references/positioning.md`
+when the CAD brief `Task type` indicates an assembly, matching the upstream SKILL.md
+reference triggers.
+
+Two additional, smaller pieces were added alongside the port, in response to review of an
+earlier scaffold plan for this repo:
+
+- `cad/script_safety.py` — an AST-based import allowlist for LLM-generated scripts, run
+  before the sandbox ever executes them. It only catches plain `import`/`from` statements,
+  not `__import__()`/`importlib`/`eval`/`exec` obfuscation — layered defense on top of the
+  subprocess sandbox in `cad/sandbox.py`, not a replacement for it.
+- `benchmarks/run_benchmarks.py` — ~8 benchmark prompts (`benchmarks/cases.py`) with
+  hand-picked expected validation targets, mirroring earthtojake's 10 benchmark prompts.
+  Run this against a real configured provider before changing prompts, repair guidance, or
+  the validation-target schema. Deliberately **not** part of `pytest -q` or CI: it makes
+  real API calls and real LLM output is non-deterministic.

dcad-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HumfDev
+
+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.

dcad-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: dcad
+Version: 0.1.0
+Summary: Text to CAD from your terminal — generate real STEP/STL/3MF/GLB files from plain-language descriptions.
+Project-URL: Homepage, https://github.com/HumfDev/derive-cad
+Project-URL: Repository, https://github.com/HumfDev/derive-cad
+Project-URL: Issues, https://github.com/HumfDev/derive-cad/issues
+Author: HumfDev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d,build123d,cad,llm,text-to-cad
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: <3.15,>=3.11
+Requires-Dist: build123d<0.12,>=0.11.1
+Requires-Dist: keyring<26,>=25.6
+Requires-Dist: litellm<2,>=1.83
+Requires-Dist: playwright<2,>=1.49
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: questionary<3,>=2.1
+Requires-Dist: rich<16,>=15.0
+Requires-Dist: tomli-w<2,>=1.0
+Requires-Dist: typer<0.27,>=0.26
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest<10,>=9.1; extra == 'dev'
+Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dcad
+
+Text to CAD from your terminal. Connect an LLM API key, pick a working folder, and describe
+what you want to build — `dcad` generates real CAD files (STEP, STL, 3MF, GLB) on disk.
+
+> **Status: Milestone 2.** `dcad run "your prompt"` sends your description to the
+> configured LLM, which writes a build123d script, runs it through vendored cadpy
+> (`skills/cad/scripts/step`), and retries on failure.
+
+## How it works
+
+Before writing any code, the configured LLM produces a CAD brief (persisted as
+`brief.md`) — dimensions, units, features, and a small set of machine-checkable
+validation targets derived from your prompt. It then writes
+[build123d](https://github.com/gumyr/build123d) — a Python parametric CAD library built
+on the OpenCASCADE kernel — which is executed via cadpy to produce a STEP file and
+optional sidecar exports (STL, 3MF, GLB).
+
+The result is checked against the brief's validation targets (bounding box, face/solid
+count). When enabled, a rendered snapshot (`snapshots/*.png`) is also reviewed by the
+same LLM; that visual review is **advisory** — deterministic checks decide pass/fail,
+and vision findings are logged without blocking acceptance when validation passes.
+Deterministic failures are classified and repaired per the vendored
+`skills/cad/references/repair-loop.md` — the LLM reads the failure output, classifies it,
+and applies the smallest source fix before rerunning.
+
+## CAD tools (upstream-shaped CLI)
+
+`dcad` mirrors the [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) skill tool layout:
+
+```bash
+dcad run "your prompt"     # full SKILL.md workflow (primary UX)
+dcad step model.py -o model.step --stl model.stl
+dcad inspect refs model.step --facts --planes --positioning
+dcad snapshot model.step   # Playwright snapshots (requires `.model.step.glb` sidecar)
+dcad open step|stl|recent  # open artifacts with your OS default app
+```
+
+The vendored skill lives at `skills/cad/` (see `skills/cad/UPSTREAM_SHA` for the pinned commit).
+
+## Install
+
+```bash
+pipx install dcad
+```
+
+Requires Python 3.11–3.14. [pipx](https://pipx.pypa.io/) keeps `dcad` and its dependencies
+(including the OpenCASCADE binding) isolated from your other Python projects.
+
+If `pipx` is not installed yet:
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+> **First release:** `dcad` is published to PyPI when a GitHub release is cut. Until then,
+> install from a built wheel with `pipx install /path/to/dcad-*.whl` or follow the source
+> setup below.
+
+**From source** (contributors):
+
+```bash
+git clone https://github.com/HumfDev/derive-cad.git
+cd derive-cad
+bash scripts/setup-dev.sh
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Do **not** also run `pip install -e packages/cadpy` — `dcad` already pulls in the vendored
+`cadpy` via `pyproject.toml`. Installing both in one command makes pip treat them as
+conflicting requirements.
+
+> **Note:** `dcad` vendors [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)'s
+> `skills/cad/` workflow and `packages/cadpy`. STEP generation and inspection use
+> `skills/cad/scripts/step` and `skills/cad/scripts/inspect`. OpenCASCADE comes via
+> `cadquery-ocp` (~60MB per platform). **Alpine/musl Docker images are not supported**; use
+> `python:3.12-slim` or similar glibc base images.
+
+## Quickstart
+
+```bash
+dcad run "design a phone stand with 45 degree angle"
+```
+
+On first use, `dcad run` launches an interactive setup wizard (LLM provider, model
+dropdown, API key, working folder) and immediately generates your model. Reconfigure any
+time with `dcad init`.
+
+`dcad run` creates a named design folder directly in your working directory — for
+example `~/derivecad-projects/phone-stand/model.stl`. The folder name is generated by your
+configured LLM from your prompt (falls back to a slug if naming fails). Each design folder
+contains `model.step`, your configured export formats (default: `model.stl`), the generated
+Python source, `brief.md` (the CAD brief the model wrote before coding),
+`snapshots/*.png` (the rendered views used for visual review), and stdout/stderr logs.
+Open the latest outputs with:
+
+```bash
+dcad open stl      # open the most recent STL in your default viewer
+dcad open step     # open the most recent STEP file
+dcad open recent   # open the most recent run folder in Finder/Files
+```
+
+Supported `open` targets: `step`, `stl`, `3mf`, `glb`, `py`, `recent`.
+
+Browse and run any command interactively:
+
+```bash
+dcad commands
+```
+
+## Supported LLM providers
+
+| Provider  | Env var            | Notes                          |
+|-----------|---------------------|---------------------------------|
+| OpenAI    | `OPENAI_API_KEY`    |                                  |
+| Anthropic | `ANTHROPIC_API_KEY` |                                  |
+| Gemini    | `GEMINI_API_KEY`    |                                  |
+| Groq      | `GROQ_API_KEY`      |                                  |
+| Ollama    | *(none)*            | Local, no API key required.     |
+| Other     | *(you choose)*      | Any [litellm](https://github.com/BerriAI/litellm)-supported model string + env var. |
+
+API keys are stored in your OS keychain via [`keyring`](https://github.com/jaraco/keyring).
+If no OS keychain backend is available (common in CI/containers/headless Linux), `dcad
+init` falls back to `~/.derivecad/credentials.toml` (mode 600) and warns you that this is
+less secure. An already-set environment variable always takes precedence over stored config.
+
+## Supported output formats
+
+STEP, STL, 3MF, GLB.
+
+## Configuration
+
+- Global config: `~/.derivecad/config.toml`
+- Per-project override: `.derivecad.toml` in your working folder
+- Precedence: CLI flags > per-project config > env vars (API keys only) > global config > defaults
+- `enable_snapshot_review` (default `true`): set to `false` to skip rendering and reviewing
+  a snapshot of each result — the release valve if the extra LLM call's cost/latency isn't
+  worth it for your use case. When enabled, vision findings are logged but do not block
+  acceptance if deterministic validation already passed. Vision review is also automatically
+  skipped (and reported as such) for models with no known vision support.
+- `bbox_tolerance_pct` (default `15.0`): tolerance applied to a brief's bounding-box
+  validation targets before a mismatch is treated as a failure.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

dcad-0.1.0/README.md

@@ -0,0 +1,152 @@
+# dcad
+
+Text to CAD from your terminal. Connect an LLM API key, pick a working folder, and describe
+what you want to build — `dcad` generates real CAD files (STEP, STL, 3MF, GLB) on disk.
+
+> **Status: Milestone 2.** `dcad run "your prompt"` sends your description to the
+> configured LLM, which writes a build123d script, runs it through vendored cadpy
+> (`skills/cad/scripts/step`), and retries on failure.
+
+## How it works
+
+Before writing any code, the configured LLM produces a CAD brief (persisted as
+`brief.md`) — dimensions, units, features, and a small set of machine-checkable
+validation targets derived from your prompt. It then writes
+[build123d](https://github.com/gumyr/build123d) — a Python parametric CAD library built
+on the OpenCASCADE kernel — which is executed via cadpy to produce a STEP file and
+optional sidecar exports (STL, 3MF, GLB).
+
+The result is checked against the brief's validation targets (bounding box, face/solid
+count). When enabled, a rendered snapshot (`snapshots/*.png`) is also reviewed by the
+same LLM; that visual review is **advisory** — deterministic checks decide pass/fail,
+and vision findings are logged without blocking acceptance when validation passes.
+Deterministic failures are classified and repaired per the vendored
+`skills/cad/references/repair-loop.md` — the LLM reads the failure output, classifies it,
+and applies the smallest source fix before rerunning.
+
+## CAD tools (upstream-shaped CLI)
+
+`dcad` mirrors the [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) skill tool layout:
+
+```bash
+dcad run "your prompt"     # full SKILL.md workflow (primary UX)
+dcad step model.py -o model.step --stl model.stl
+dcad inspect refs model.step --facts --planes --positioning
+dcad snapshot model.step   # Playwright snapshots (requires `.model.step.glb` sidecar)
+dcad open step|stl|recent  # open artifacts with your OS default app
+```
+
+The vendored skill lives at `skills/cad/` (see `skills/cad/UPSTREAM_SHA` for the pinned commit).
+
+## Install
+
+```bash
+pipx install dcad
+```
+
+Requires Python 3.11–3.14. [pipx](https://pipx.pypa.io/) keeps `dcad` and its dependencies
+(including the OpenCASCADE binding) isolated from your other Python projects.
+
+If `pipx` is not installed yet:
+
+```bash
+brew install pipx
+pipx ensurepath
+```
+
+> **First release:** `dcad` is published to PyPI when a GitHub release is cut. Until then,
+> install from a built wheel with `pipx install /path/to/dcad-*.whl` or follow the source
+> setup below.
+
+**From source** (contributors):
+
+```bash
+git clone https://github.com/HumfDev/derive-cad.git
+cd derive-cad
+bash scripts/setup-dev.sh
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Do **not** also run `pip install -e packages/cadpy` — `dcad` already pulls in the vendored
+`cadpy` via `pyproject.toml`. Installing both in one command makes pip treat them as
+conflicting requirements.
+
+> **Note:** `dcad` vendors [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)'s
+> `skills/cad/` workflow and `packages/cadpy`. STEP generation and inspection use
+> `skills/cad/scripts/step` and `skills/cad/scripts/inspect`. OpenCASCADE comes via
+> `cadquery-ocp` (~60MB per platform). **Alpine/musl Docker images are not supported**; use
+> `python:3.12-slim` or similar glibc base images.
+
+## Quickstart
+
+```bash
+dcad run "design a phone stand with 45 degree angle"
+```
+
+On first use, `dcad run` launches an interactive setup wizard (LLM provider, model
+dropdown, API key, working folder) and immediately generates your model. Reconfigure any
+time with `dcad init`.
+
+`dcad run` creates a named design folder directly in your working directory — for
+example `~/derivecad-projects/phone-stand/model.stl`. The folder name is generated by your
+configured LLM from your prompt (falls back to a slug if naming fails). Each design folder
+contains `model.step`, your configured export formats (default: `model.stl`), the generated
+Python source, `brief.md` (the CAD brief the model wrote before coding),
+`snapshots/*.png` (the rendered views used for visual review), and stdout/stderr logs.
+Open the latest outputs with:
+
+```bash
+dcad open stl      # open the most recent STL in your default viewer
+dcad open step     # open the most recent STEP file
+dcad open recent   # open the most recent run folder in Finder/Files
+```
+
+Supported `open` targets: `step`, `stl`, `3mf`, `glb`, `py`, `recent`.
+
+Browse and run any command interactively:
+
+```bash
+dcad commands
+```
+
+## Supported LLM providers
+
+| Provider  | Env var            | Notes                          |
+|-----------|---------------------|---------------------------------|
+| OpenAI    | `OPENAI_API_KEY`    |                                  |
+| Anthropic | `ANTHROPIC_API_KEY` |                                  |
+| Gemini    | `GEMINI_API_KEY`    |                                  |
+| Groq      | `GROQ_API_KEY`      |                                  |
+| Ollama    | *(none)*            | Local, no API key required.     |
+| Other     | *(you choose)*      | Any [litellm](https://github.com/BerriAI/litellm)-supported model string + env var. |
+
+API keys are stored in your OS keychain via [`keyring`](https://github.com/jaraco/keyring).
+If no OS keychain backend is available (common in CI/containers/headless Linux), `dcad
+init` falls back to `~/.derivecad/credentials.toml` (mode 600) and warns you that this is
+less secure. An already-set environment variable always takes precedence over stored config.
+
+## Supported output formats
+
+STEP, STL, 3MF, GLB.
+
+## Configuration
+
+- Global config: `~/.derivecad/config.toml`
+- Per-project override: `.derivecad.toml` in your working folder
+- Precedence: CLI flags > per-project config > env vars (API keys only) > global config > defaults
+- `enable_snapshot_review` (default `true`): set to `false` to skip rendering and reviewing
+  a snapshot of each result — the release valve if the extra LLM call's cost/latency isn't
+  worth it for your use case. When enabled, vision findings are logged but do not block
+  acceptance if deterministic validation already passed. Vision review is also automatically
+  skipped (and reported as such) for models with no known vision support.
+- `bbox_tolerance_pct` (default `15.0`): tolerance applied to a brief's bounding-box
+  validation targets before a mismatch is treated as a failure.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT