create/README.md

# Kindred Create

**An engineering-focused parametric 3D CAD platform built on FreeCAD 1.0+**

Kindred Create 0.1.0 | FreeCAD 1.2.0 base

[Website](https://www.kindred-systems.com/create) |
[Downloads](https://git.kindred-systems.com/kindred/create/releases) |
[Issue Tracker](https://git.kindred-systems.com/kindred/create/issues) |
[Documentation](https://docs.kindred-systems.com/create)

> Kindred Create is in active development. Features and interfaces may change.

---

## What is Kindred Create?

Kindred Create is a fork of [FreeCAD](https://www.freecad.org) that adds integrated tooling for professional engineering workflows. It ships a context-aware UI system, two addon command sets, a purpose-built dark theme, and a pluggable file origin layer on top of FreeCAD's parametric modeling core.

**Editing context system** -- The UI adapts to what you are editing. An `EditingContextResolver` tracks the active document, view, and in-edit object, then shows or hides toolbars automatically. Built-in contexts cover sketcher editing, assembly editing, PartDesign features/bodies, spreadsheets, and idle states. Addons register their own contexts through a Python API. A color-coded breadcrumb bar in the 3D viewport shows the current editing path.

**ztools** -- A command provider that injects velocity-focused tools into FreeCAD's native PartDesign, Assembly, and Spreadsheet workbenches. Adds custom datum creation (planes, axes, points with 15 attachment modes), pattern tools for assemblies, an enhanced pocket with flip-side cutting, and spreadsheet formatting commands. Rather than running as a separate workbench, ztools commands appear contextually via the editing context system.

**Silo** -- A parts lifecycle management system for managing CAD files, part numbers, revisions, and bills of materials across teams. Includes a Go REST API server backed by PostgreSQL and MinIO, with FreeCAD commands for opening, saving, and syncing files directly from the application. A unified origin system integrates Silo file operations (New, Open, Save, Commit, Pull, Push) into the standard File toolbar and menu across all workbenches. Dock panels provide authentication, real-time database activity via SSE, and a custom start page that replaces the default FreeCAD landing.

**Catppuccin Mocha theme** -- A dark theme applied across the entire application, including the 3D viewport, sketch editor, spreadsheet view, and tree view. Uses spanning-line branch indicators instead of disclosure arrows. Includes tuned preference defaults for document handling, selection behavior, notifications, and report view settings.

**Update checker** -- On startup, Kindred Create checks the Gitea releases API for newer versions and logs the result. Configurable check interval and skip-version preferences.

Kindred Create is maintained by [Kindred Systems LLC](https://www.kindred-systems.com).

---

## Platform support

| Platform | Packages | Status |
|---|---|---|
| Linux x86_64 | AppImage, .deb | Builds and releases in CI |
| Linux aarch64 | -- | Build configuration ready, no CI runner yet |
| macOS Intel | DMG | Build preset defined, no CI runner yet |
| macOS Apple Silicon | DMG | Build preset defined, no CI runner yet |
| Windows x64 | NSIS installer, .7z | Build preset defined, no CI runner yet |

---

## Installing

### Prebuilt packages (Linux)

Download from the [releases page](https://git.kindred-systems.com/kindred/create/releases).

**Debian/Ubuntu:**

```bash
sudo apt install ./kindred-create_*.deb
```

**AppImage:**

```bash
chmod +x KindredCreate-*.AppImage
./KindredCreate-*.AppImage
```

### Building from source

Kindred Create uses [pixi](https://pixi.sh) for dependency management and CMake for building.

```bash
git clone --recursive ssh://git@git.kindred-systems.com:2222/kindred/create.git
cd create
pixi run configure
pixi run build
pixi run install
pixi run freecad
```

Debug and release variants are available (`pixi run build-debug`, `pixi run build-release`). See `CMakePresets.json` for platform-specific presets covering Linux, macOS, and Windows.

`pixi run test` runs the C++ test suite via ctest.

For general FreeCAD compilation guidance, see the FreeCAD wiki for [Linux](https://wiki.freecad.org/Compile_on_Linux), [Windows](https://wiki.freecad.org/Compile_on_Windows), or [macOS](https://wiki.freecad.org/Compile_on_MacOS).

---

## Architecture

### Editing context system

FreeCAD's stock UI presents a flat set of workbenches that the user switches between manually. Kindred Create replaces this with a context-driven model: as you open documents, enter edit mode on a sketch, or select a PartDesign body, the `EditingContextResolver` (C++, `src/Gui/EditingContext.h`) evaluates registered context definitions in priority order and activates the matching one. Activation sets toolbar visibility via `ToolBarManager::setState(ForceAvailable)` and updates the breadcrumb bar.

Built-in contexts:

| Context ID | When active |
|---|---|
| `sketcher.edit` | Editing a Sketch object |
| `assembly.edit` | Editing an Assembly |
| `partdesign.feature` | Editing a PartDesign feature (pad, pocket, etc.) |
| `partdesign.body` | A PartDesign Body is selected |
| `assembly.idle` | An Assembly document is open but not in edit |
| `spreadsheet` | A Spreadsheet view is active |
| `empty_document` | An empty document is open |
| `no_document` | No document is open |

Addons extend this through the Python API:

- `FreeCADGui.registerEditingContext()` -- register a new context with match function, toolbars, and priority
- `FreeCADGui.registerEditingOverlay()` -- register an overlay that conditionally adds toolbars on top of any context
- `FreeCADGui.injectEditingCommands()` -- add commands to an existing context's toolbars
- `FreeCADGui.currentEditingContext()` -- query the active context
- `FreeCADGui.refreshEditingContext()` -- force a re-evaluation

### Addon integration

Both ztools and Silo are loaded by the `src/Mod/Create/` bootstrap module, which executes their `Init.py` and `InitGui.py` files at startup. Neither requires the user to switch workbenches. Instead, they register commands and use the editing context system to make those commands visible in the appropriate situations.

ztools uses a `WorkbenchManipulator` plus `injectEditingCommands()` to add its tools to PartDesign, Assembly, and Spreadsheet contexts. Silo registers an overlay that adds the "Silo Origin" toolbar whenever the active document contains Silo tracking properties (`SiloItemId`, `SiloPartNumber`).

### Unified origin system

File operations (New, Open, Save, etc.) are abstracted behind a `FileOrigin` interface. The default `LocalFileOrigin` handles standard filesystem operations. When Silo is connected, `SiloOrigin` provides the same interface backed by the Silo server, adding revision control, part numbers, and remote storage. The active origin is selected automatically based on whether the current document is tracked by Silo.

---

## Usage

Kindred Create is compatible with standard FreeCAD workflows. The [FreeCAD wiki](https://wiki.freecad.org/Getting_started) covers general usage.

### ztools

ZTools commands appear automatically in the PartDesign, Assembly, and Spreadsheet toolbars. There is no separate workbench to select.

**Datum tools** -- A unified datum creator supporting 15 attachment modes for planes, axes, and points. Accessed from the PartDesign toolbar.

**PartDesign tools** -- Enhanced pocket with face selection and flip-side cutting. Rotated linear pattern.

**Assembly tools** -- Linear and polar pattern commands for creating component arrays within assemblies.

**Spreadsheet tools** -- Bold, italic, underline, alignment (left/center/right), background and text color, and a quick-alias command that creates aliases from cell labels.

See `mods/ztools/` for detailed documentation.

### Silo

Silo requires a running server instance. See `mods/silo/README.md` for server deployment instructions.

The FreeCAD workbench reads configuration from:
- `SILO_API_URL` -- Server API endpoint (default: `http://localhost:8080/api`)
- `SILO_PROJECTS_DIR` -- Local projects directory (default: `~/projects`)

On first launch, Kindred Create prompts for Silo server configuration. Silo commands are available in the File menu across all workbenches:

| Command | Shortcut | Description |
|---|---|---|
| New | Ctrl+N | Create a new item with part number |
| Open | Ctrl+O | Search and open items from the database |
| Save | Ctrl+S | Save locally and upload to MinIO |
| Commit | Ctrl+Shift+S | Save with a revision comment |
| Pull | -- | Download the latest revision from the server |
| Push | -- | Upload local changes |
| BOM | -- | Edit the bill of materials |
| Info | -- | View item metadata and revision history |
| Rollback | -- | Restore a previous revision |

The authentication dock panel (right side) manages server login. The activity panel shows recent database changes in real time via server-sent events.

---

## Project structure

```
create/
├── src/
│   ├── App/                    # Core application (C++)
│   ├── Base/                   # Base classes, type system, persistence (C++)
│   ├── Gui/                    # GUI framework (C++)
│   │   ├── EditingContext.h    #   Editing context resolver
│   │   ├── BreadcrumbToolBar.h #   Breadcrumb navigation widget
│   │   ├── Stylesheets/       #   QSS theme files
│   │   └── PreferencePacks/   #   Theme and preference configurations
│   ├── Mod/                    # FreeCAD modules (PartDesign, Assembly, Sketcher, ...)
│   │   └── Create/            # Kindred bootstrap module -- loads ztools and Silo
│   └── 3rdParty/              # Vendored dependencies
│       ├── OndselSolver/      #   Assembly constraint solver (forked)
│       └── GSL/               #   Microsoft Guidelines Support Library
├── mods/                       # Kindred addon modules (git submodules)
│   ├── ztools/                # ztools command provider
│   └── silo/                  # Silo PLM workbench
├── resources/                  # Branding, icons, desktop integration, MIME types
├── package/                    # Packaging scripts
│   ├── debian/                #   .deb build script
│   └── rattler-build/         #   AppImage/DMG/Windows bundling
├── docs/                       # mdBook documentation site
├── .gitea/workflows/           # CI/CD (build, release, docs deployment)
├── CMakeLists.txt              # Root build configuration
├── CMakePresets.json           # Platform build presets (Linux, macOS, Windows)
└── pixi.toml                  # Pixi environment and build tasks
```

The `mods/` addons and `src/3rdParty/` dependencies are git submodules. If you cloned without `--recursive`, initialize them with:

```bash
git submodule update --init --recursive
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide, including branch workflow, commit message conventions, code style, submodule management, and theme change procedures.

## Reporting issues

Report issues at the [issue tracker](https://git.kindred-systems.com/kindred/create/issues). When reporting:

1. Note whether the issue involves Kindred Create additions (ztools, Silo, theme, editing contexts) or base FreeCAD
2. Include version info from **Help > About FreeCAD > Copy to clipboard**
3. Provide reproduction steps and attach example files (FCStd as ZIP) if applicable

For base FreeCAD issues, also check the [FreeCAD issue tracker](https://github.com/FreeCAD/FreeCAD/issues).

---

## License

[LGPL-2.1-or-later](LICENSE), consistent with FreeCAD.

## Acknowledgments

Built on [FreeCAD](https://www.freecad.org) and its ecosystem: [OpenCASCADE](https://www.opencascade.com/), [Coin3D](https://github.com/coin3d/coin), [Qt](https://www.qt.io/), [Python](https://www.python.org/). Theme colors from [Catppuccin](https://github.com/catppuccin/catppuccin).