# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**WoodShop** - Voice-driven conversational 3D woodworking & furniture modeler.
Speak (or type) commands like *"place a 6 foot 2x4, sand it, attach a 2 foot 2x4
at 90 degrees 10 inches from the end"* and watch the model build in a live 3D
viewport — Holodeck-style.

## Architecture

**Design principle:** reuse existing CmdForge tools for everything that isn't
woodshop-specific; don't reinvent voice/AI plumbing.

```
woodshop-talk (driver.py) ── the conversational loop
   │  dictate ............... speech→text         (CmdForge tool, reused)
   │  pa-load-tools ......... wood-* → Claude schemas (reused)
   │  claude -p ............. interpret utterance → JSON tool calls (reused provider)
   │  pa-execute-tool ....... dispatch each wood-* tool (reused)
   │  read-aloud ........... speak confirmation   (reused)
   ▼
scene.json  ← single source of truth (parts, joints, selection, undo stack)
   ▲                                   │ writes
   │ reads/mutates                     ▼
wood-* CmdForge tools          woodshop-view (viewer.py)
(place/join/sand/delete/undo)  watches scene.json → live pyvista 3D
thin wrappers over `woodshop` CLI
```

Only woodshop-specific code lives in this repo: the scene model
(`scene.py`), nominal→actual lumber table (`lumber.py`), length parsing
(`units.py`), the `woodshop` CLI (`cli.py`), build123d geometry + STL/STEP
export (`geometry.py`), the pyvista viewport (`viewer.py`), and the driver
(`driver.py`). The driver uses Claude (not `pa-tool-loop`, which hard-wires a
small local model) for reliable structured tool-calling.

### Entry points

| Command | Purpose |
|---------|---------|
| `woodshop <op>` | CLI: `place`, `join`, `sand`, `delete`, `undo`, `export`, `status` |
| `woodshop-view` | Live 3D viewport (watches `scene.json`) |
| `woodshop-talk` | Conversational driver (`--voice` for mic, `--once "..."` for one command) |

Scene file location: `$WOODSHOP_SCENE` or `~/.local/share/woodshop/scene.json`.

### CmdForge tools (the documented command vocabulary)

`wood-place`, `wood-join`, `wood-sand`, `wood-delete`, `wood-undo` live in
`~/.cmdforge/<name>/` and wrap the `woodshop` CLI. Regenerate them with
`/tmp/gen_wood_tools.py` (kept in the repo plan) if their schemas change. The
arg descriptions ARE the LLM's documentation, so keep them clear.

### Setup

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[viewer,dev]"   # viewer extra pulls build123d + pyvista
pytest                            # 25 tests
```

### Known limitations / next steps

1. **No vertical orientation.** Boards only rotate in the horizontal (XY) plane
   (`rotation_deg` about Z). Furniture legs that "stand up" (length along Z)
   aren't representable yet — this is the top priority for real furniture.
2. **Joins stack in Z** (board B rests on B's top face). This avoids
   interpenetration but isn't true joinery (no butt/mortise/lap geometry).
3. **Latency** ~7–13s per utterance (one `claude -p` call). Fine for now.
4. Voice path (`--voice`) reuses `dictate`; not yet exercised on real hardware
   in this repo's tests.

## ⚠️ CRITICAL: Updating Todos, Milestones, and Goals

**DO NOT edit `todos.md`, `milestones.md`, or `goals.md` files directly.**

These files are managed by Development Hub which has file watchers and sync logic. Direct edits will be overwritten or cause conflicts.

**Use the `devhub-tasks` CLI instead:**

```bash
# Status overview
devhub-tasks status woodshop

# Add todos
devhub-tasks todo add woodshop "Task description" --priority high --milestone M1

# Complete todos (by text match or ID number)
devhub-tasks todo complete woodshop "Task description"
devhub-tasks todo complete woodshop 3

# List todos
devhub-tasks todo list woodshop

# Add milestones
devhub-tasks milestone add woodshop M2 --name "Milestone Name" --target "March 2026"

# Complete milestones (also completes linked todos)
devhub-tasks milestone complete woodshop M1

# Goals
devhub-tasks goal add woodshop "Goal description" --priority high
devhub-tasks goal complete woodshop "Goal description"
```

Use `--json` flag for machine-readable output. Run `devhub-tasks --help` for full documentation.

**Files you CAN edit directly:** `overview.md`, `architecture.md`, `README.md`, and any other docs.

## Development Commands

```bash
# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Run a single test
pytest tests/test_file.py::test_name
```

## Architecture

*TODO: Describe the project architecture*

### Key Modules

*TODO: List key modules and their purposes*

### Key Paths

- **Source code**: `src/woodshop/`
- **Tests**: `tests/`
- **Documentation**: `docs/` (symlink to project-docs)

## Documentation

Documentation lives in `docs/` (symlink to centralized docs system).

**Before updating docs, read `docs/updating-documentation.md`** for full details on visibility rules and procedures.

Quick reference:
- Edit files in `docs/` folder
- Use `public: true` frontmatter for public-facing docs
- Use `<!-- PRIVATE_START -->` / `<!-- PRIVATE_END -->` to hide sections
- Deploy: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh woodshop --deploy`

Do NOT create documentation files directly in this repository.