# AgentCAD

AgentCAD is an independent, agent-oriented parametric CAD platform built on
FreeCAD. It provides a controlled MCP gateway, typed CAD operations, structured
inspection, transactions, diagnostics, and reproducible verification for
engineering agents.

Current display version: `0.0.1-15-07-2026` (pre-alpha; no functional release
has been published).

AgentCAD is not maintained, approved, or endorsed by the FreeCAD project.

## Purpose

AgentCAD will provide a controlled MCP interface for engineering agents, headless and GUI CAD execution, reproducible regression testing, diagnostic artifacts, and a disciplined route for human-reviewed upstream contributions.

It is a distinct product distribution. Product features and agent-specific changes may evolve independently from FreeCAD, while small compatible fixes can be prepared separately for human adoption and possible upstream submission.

## Relationship to FreeCAD

This repository contains AgentCAD-owned code only: the Rust MCP gateway, typed worker protocol, Python CAD worker, installable AgentCAD bridge, CAD-IR schemas, tests, documentation, and candidate-fix evidence.

FreeCAD remains authoritative at [FreeCAD/FreeCAD](https://github.com/FreeCAD/FreeCAD).
Its source and history are not merged into this repository. The tested upstream
revision is recorded in [`upstream/freecad.json`](upstream/freecad.json), and
the fetch scripts clone that revision into a separate sibling checkout.

The companion [`Getopir/FreeCAD`](https://github.com/Getopir/FreeCAD) repository
is a history-free, squashed source snapshot used for AgentCAD builds. It is a
standalone repository, not a member of GitHub's `FreeCAD/FreeCAD` fork network.
This is intentional: a GitHub fork retains its upstream relationship and
history, while AgentCAD keeps its product history and upstream candidate-fix
workflow separate.

FreeCAD issues and pull requests remain authoritative upstream. AgentCAD's
[issue tracker](https://github.com/Getopir/AgentCAD/issues) is for AgentCAD
features, defects, integration work, and locally tracked candidate evidence.

## Repository layout

- `agentcad/` — Rust MCP gateway, protocol crates, Python worker, schemas, and tests.
- `agentcad-bridge/` — installable FreeCAD integration bridge.
- `workbenches/` — governed AgentCAD workbench registry and templates.
- `docs/` and `wiki/` — normative documentation and reviewed GitHub Wiki source.
- `upstream/` — pinned FreeCAD source metadata and synchronization records.
- `work-items/` — AgentCAD delivery records and human-adoptable upstream evidence.

## Branches

- `main` is the AgentCAD product branch. It need not be directly upstreamable.
- `feature/<topic>` is for product features.
- `agentcad-fix/<id>-<topic>` is for product-only fixes based on `main`.
- `upstream-fix/<issue>-<topic>` is created in a separate FreeCAD checkout at the pinned upstream commit. Only the evidence package and patch belong in AgentCAD.

See [the architecture](docs/architecture.md), [the MCP operation contract](docs/mcp-operation-contract.md), [diagnostics](docs/DIAGNOSTICS_AND_LOGGING.md), [versioning](docs/VERSIONING.md), [the workbench agent instruction](docs/WORKBENCH_AGENT_INSTRUCTION.md), [the upstream-intake data model](docs/upstream-intake-data-model.md), and [the upstream candidate policy](docs/upstream-candidate-policy.md).

Changes reach protected `main` through current, tested pull requests with independent approval. See [the review and merge workflow](docs/REVIEW_AND_MERGE_WORKFLOW.md).

GitHub is the public source host. The migration design, cutover sequence, and
the reason AgentCAD is not itself a FreeCAD fork are documented in
[`docs/GITHUB_MIGRATION.md`](docs/GITHUB_MIGRATION.md).

## LLM instruction package

The complete lead-agent and contributor instruction package is published at [AgentCAD-instructions/README.md](AgentCAD-instructions/README.md). It contains the master implementation contract, persistent repository instructions, MCP interface specification, bootstrap checklist, upstream-fix workflow, and reusable contributor-agent prompt.

The root [AGENTS.md](AGENTS.md) and normative files under [docs/](docs/) remain the active repository copies. The package directory preserves the supplied bundle intact for discovery and reuse.

## Status

The Rust MCP gateway and structured Python worker are implemented and tested without unrestricted Python execution. Native FreeCAD build and GUI verification will run on the dedicated development machine when it is available.

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change, then open a
GitHub pull request against `main`. Candidate upstream patches require a human
adopter who understands, tests, reviews, and personally submits the
contribution.

## License

AgentCAD-owned source is licensed under `LGPL-2.1-or-later`, matching FreeCAD's compatible LGPL licensing model. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).