create/CLAUDE.md

CLAUDE.md — Developer Context for Kindred Create

Project Overview

Kindred Create is a fork of FreeCAD 1.0+ that adds integrated tooling for professional engineering workflows. It ships a context-aware UI system, five addon modules (SDK, Gears, Datums, Silo, Solver), a KCSDK C++ extension layer, a Catppuccin Mocha dark theme, and a pluggable file origin layer on top of FreeCAD's parametric modeling core.

• Kindred Create version: 0.1.5
• FreeCAD base version: 1.2.0
• License: LGPL-2.1-or-later
• Repository: git.kindred-systems.com/kindred/create (Gitea)
• Main branch: main

Quick Start

git clone --recursive ssh://git@git.kindred-systems.com:2222/kindred/create.git
cd create
pixi run configure      # CMake configure (debug by default)
pixi run build          # Build
pixi run install        # Install to build dir
pixi run freecad        # Launch
pixi run test           # Run C++ tests (ctest)
pixi run test-kindred   # Run Python/Kindred tests

Build variants: append -debug or -release (e.g., pixi run build-release). See CMakePresets.json for platform-specific presets (Linux x86_64/aarch64, macOS Intel/ARM, Windows x64).

Repository Structure

create/
├── src/
│   ├── App/                    Core application (C++)
│   ├── Base/                   Base classes, type system, persistence (C++)
│   ├── Gui/                    GUI framework (C++)
│   │   ├── SDK/                KCSDK C++ library (Kindred feature)
│   │   │   ├── bindings/       pybind11 module (kcsdk.so)
│   │   │   ├── IPanelProvider.h    Dock panel interface
│   │   │   ├── IToolbarProvider.h  Toolbar interface
│   │   │   ├── IMenuProvider.h     Menu interface
│   │   │   ├── SDKRegistry.h       Provider registry
│   │   │   ├── ThemeEngine.h       Runtime theme token access
│   │   │   └── WidgetBridge.h      Qt widget creation bridge
│   │   ├── EditingContext.h    Editing context resolver (Kindred feature)
│   │   ├── BreadcrumbToolBar.h Breadcrumb navigation widget (Kindred feature)
│   │   ├── FileOrigin.h        Abstract origin interface (Kindred feature)
│   │   ├── OriginManager.h     Origin lifecycle management
│   │   ├── CommandOrigin.cpp   Origin_Commit/Pull/Push/Info/BOM commands
│   │   ├── ApplicationPy.h     All FreeCADGui.* Python bindings
│   │   ├── Application.h       App signals (fastsignals)
│   │   ├── Stylesheets/        QSS theme files
│   │   └── PreferencePacks/    Preference configurations (build-time generated)
│   ├── Mod/                    FreeCAD modules (PartDesign, Assembly, Sketcher, etc.)
│   │   └── Create/            Kindred Create module
│   │       ├── App/            C++ app-side module (AppCreate)
│   │       ├── Gui/            C++ GUI-side module (AppCreateGui)
│   │       ├── Init.py         Console bootstrap — loads addons
│   │       ├── InitGui.py      GUI bootstrap — loads addons, kc_format, update checker
│   │       ├── addon_loader.py Manifest-driven loader with dependency resolution
│   │       ├── kc_format.py    .kc file format preservation
│   │       ├── silo_document.py .kc tree building observer
│   │       ├── silo_tree.py    Silo metadata tree builder
│   │       ├── silo_objects.py  Silo tree FeaturePython objects
│   │       ├── silo_viewers.py  Silo tree MDI viewers
│   │       └── silo_viewproviders.py  Silo tree ViewProvider icons
│   └── 3rdParty/              Vendored dependencies
│       ├── OndselSolver/      [submodule] Assembly constraint solver (forked)
│       ├── FastSignals/       Signal/slot library (NOT Boost)
│       └── GSL/               [submodule] Microsoft Guidelines Support Library
├── mods/                       Kindred addon modules
│   ├── sdk/                   Addon SDK — stable API contract (priority 0)
│   ├── gears/                 [submodule] Parametric gear workbench (priority 40)
│   ├── datums/                [submodule] Unified datum creator (priority 45)
│   ├── silo/                  [submodule] PLM workbench (priority 60)
│   └── solver/                [submodule] Assembly solver research (priority 10)
├── reference/                  Archived addons (not built)
│   ├── ztools/                Archived — commands migrated to datums + core
│   └── quicknav/              Archived — navigation addon
├── docs/                       mdBook documentation + architecture docs
├── tests/                      C++ unit tests (GoogleTest)
├── package/                    Packaging (debian/, rattler-build/)
├── resources/                  Branding, icons, desktop integration
├── cMake/                      CMake helper modules
├── .gitea/workflows/           CI/CD pipelines
├── CMakeLists.txt              Root build configuration (CMake 3.22.0+)
├── CMakePresets.json           Platform build presets
└── pixi.toml                  Pixi environment and build tasks

Build System

• Primary: CMake 3.22.0+ with Ninja generator
• Environment: Pixi (conda-forge) manages all dependencies
• Key deps: Qt 6.8.x, Python 3.11.x, OpenCASCADE 7.8.x, PySide6, Boost, VTK, SMESH
• Presets: conda-linux-debug, conda-linux-release, conda-macos-debug, conda-macos-release, conda-windows-debug, conda-windows-release
• Tasks summary:

Task	Description
pixi run configure	CMake configure (debug)
pixi run build	Build (debug)
pixi run install	Install to build dir
pixi run freecad	Launch FreeCAD
pixi run test	C++ tests via ctest
pixi run test-kindred	Python/Kindred test suite

Architecture Patterns

Signals — Use FastSignals, NOT Boost

#include <fastsignals/signal.h>
// See src/Gui/Application.h:121-155 for signal declarations

All signals in src/Gui/ use fastsignals::signal. Never use Boost.Signals2.

Type Checking Across Modules

Avoid header dependencies between src/Gui/ and src/Mod/ by using runtime type checks:

auto type = Base::Type::fromName("Sketcher::SketchObject");
if (obj->isDerivedFrom(type)) { ... }

Python Bindings

All FreeCADGui.* functions go in src/Gui/ApplicationPy.h and src/Gui/ApplicationPy.cpp. Use METH_VARARGS only (no METH_KEYWORDS in this file). Do not create separate files for new Python bindings.

KCSDK C++ Layer

The src/Gui/SDK/ directory provides a C++ shared library (libKCSDK) with pybind11 bindings (kcsdk Python module). This is the stable C++ API for Kindred features:

• IPanelProvider — interface for registering dock panels
• IToolbarProvider — interface for toolbar registration
• IMenuProvider — interface for menu registration
• SDKRegistry — central registry for all providers
• ThemeEngine — runtime access to Catppuccin Mocha theme tokens
• WidgetBridge — Qt widget creation from Python factories

Python addons access these through kindred_sdk.* wrappers (e.g., kindred_sdk.register_dock_panel() routes through kcsdk.register_panel() + kcsdk.create_panel()). Do not use kcsdk directly from addons — always use kindred_sdk.

Toolbar Visibility

Use ToolBarItem::DefaultVisibility::Unavailable to hide toolbars by default, then ToolBarManager::setState(ForceAvailable) to show them contextually. This pattern is proven by the Sketcher module.

The appendToolbar Python API accepts an optional 3rd argument: "Visible", "Hidden", or "Unavailable".

Editing Context System

The EditingContextResolver singleton (src/Gui/EditingContext.h/.cpp) drives the context-aware UI. It evaluates registered context definitions in priority order and activates the matching one, setting toolbar visibility and updating the BreadcrumbToolBar.

Built-in contexts: sketcher.edit, assembly.edit, partdesign.feature, partdesign.body, assembly.idle, spreadsheet, empty_document, no_document.

Python API (prefer kindred_sdk wrappers over direct FreeCADGui calls):

• kindred_sdk.register_context() — register a new context
• kindred_sdk.register_overlay() — conditional toolbar overlay
• kindred_sdk.inject_commands() — add commands to existing contexts
• kindred_sdk.current_context() — query active context
• kindred_sdk.refresh_context() — force re-evaluation

Addon Loading

Addons in mods/ are loaded by src/Mod/Create/addon_loader.py. Each addon provides a package.xml at the mod root with <kindred> extensions declaring version bounds, load priority, and dependencies. The loader discovers manifests, validates version bounds, and resolves load order via topological sort on dependencies, breaking ties by (load_priority, name).

Current load order: sdk (0) → solver (10) → gears (40) → datums (45) → silo (60).

A <workbench> tag in package.xml is required for InitGui.py to be loaded, even if no actual workbench is registered. The <subdirectory> element within <workbench> specifies where Init.py/InitGui.py live relative to the mod root (e.g., freecad for silo, datums for datums, ./ for sdk).

Deferred Initialization

GUI setup uses QTimer.singleShot with staggered delays. Create core (src/Mod/Create/InitGui.py) handles:

• 500ms: .kc file format registration
• 10000ms: Update checker

Each addon manages its own deferred setup in its InitGui.py. For example, Silo (mods/silo/InitGui.py) defers:

• 500ms: kindred:// URL handler
• 600ms: Document observer for .kc tree building
• 2000ms: Auth dock panel (via kindred_sdk.register_dock_panel)
• 2500ms: Silo overlay context
• 3000ms: First-start settings check
• 4000ms: Activity dock panel (via kindred_sdk.register_dock_panel)

Unified Origin System

File operations (New, Open, Save, Commit, Pull, Push) are abstracted behind FileOrigin (src/Gui/FileOrigin.h). LocalFileOrigin handles local files; SiloOrigin (mods/silo/freecad/silo_origin.py) backs Silo-tracked documents. The active origin is selected automatically based on document properties (SiloItemId, SiloPartNumber).

Origins are registered via kindred_sdk.register_origin(). Query functions (list_origins, active_origin, get_origin, set_active_origin) route through the kcsdk C++ module.

Submodules

Path	Repository	Branch	Purpose
mods/silo	git.kindred-systems.com/kindred/silo-mod	main	PLM workbench (includes silo-client submodule)
mods/gears	git.kindred-systems.com/kindred/gears	main	Parametric gear generation workbench
mods/datums	git.kindred-systems.com/kindred/datums	main	Unified datum creator (plane, axis, point)
mods/solver	git.kindred-systems.com/kindred/solver	main	Assembly solver research (GNN-based)
src/3rdParty/OndselSolver	git.kindred-systems.com/kindred/solver	—	Constraint solver (forked with NR fix)
src/3rdParty/GSL	github.com/microsoft/GSL	—	Guidelines Support Library
src/Mod/AddonManager	github.com/FreeCAD/AddonManager	—	FreeCAD addon manager
tests/lib	github.com/google/googletest	—	C++ test framework

Update a submodule:

cd mods/silo
git checkout main && git pull
cd ../..
git add mods/silo
git commit -m "chore: update silo submodule"

Initialize all submodules: git submodule update --init --recursive

Key Addon Modules

SDK (mods/sdk/)

Stable API contract for addons. Python package kindred_sdk wraps the KCSDK C++ module, providing:

• Editing contexts: register_context(), register_overlay(), inject_commands(), refresh_context()
• Origins: register_origin(), unregister_origin(), list_origins(), active_origin()
• Dock panels: register_dock_panel(object_name, title, factory, area, delay_ms)
• Commands: register_command(cmd_id, classname, pixmap, tooltip)
• Theme: get_theme_tokens(), load_palette() (Catppuccin Mocha YAML palette)
• Toolbars/Menus: register_toolbar(), register_menu()
• Version: create_version(), freecad_version()

Addons should use kindred_sdk.* instead of FreeCADGui.* internals where possible.

Gears (mods/gears/)

Parametric gear workbench. Provides GearWorkbench with gear generation and analysis tools. Code lives in freecad/gears/ (workbench) and pygears/ (computational library). Priority 40, depends on SDK.

Datums (mods/datums/)

Unified datum creator that replaces the three stock PartDesign datum commands (Plane, Line, Point) with a single Create_DatumCreator command. Features:

• 16 smart creation modes (7 plane, 4 axis, 5 point)
• Auto-detection engine: selects best mode from geometry selection
• Mode override combo for manual selection
• Dynamic parameter UI (offset, angle, position, XYZ)
• Edit panel with real-time parameter updates via AttachExtension
• Injected into partdesign.body and partdesign.feature contexts via SDK

Source: mods/datums/datums/ (command.py, core.py, panel.py, detection.py, edit_panel.py). Priority 45, depends on SDK.

Silo (mods/silo/)

PLM workbench with 14 commands for parts lifecycle management. Go REST API server + PostgreSQL + MinIO backend. FreeCAD client communicates via shared silo-client submodule.

Structure: root-level package.xml/Init.py/InitGui.py, workbench code in freecad/, client library in silo-client/. All deferred setup (origin, overlay, dock panels, document observer) is self-contained in mods/silo/InitGui.py.

Silo origin detection: silo_origin.py:ownsDocument() checks for SiloItemId/SiloPartNumber properties on the active document. Origin registered via kindred_sdk.register_origin().

Solver (mods/solver/)

Assembly solver research addon (GNN-based). Pure Python, priority 10. Provides KindredSolverBackend for experimental assembly constraint solving.

Theme

• Canonical source: src/Gui/Stylesheets/KindredCreate.qss
• The PreferencePacks copy at src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss is generated at build time via configure_file(). Only edit the Stylesheets copy.
• Color palette: Catppuccin Mocha (26 colors + 14 semantic roles, defined in mods/sdk/kindred_sdk/palettes/catppuccin-mocha.yaml)
• Runtime access: kindred_sdk.get_theme_tokens() returns palette dict; C++ side via ThemeEngine in src/Gui/SDK/
• Default preferences: src/Gui/PreferencePacks/KindredCreate/KindredCreate.cfg

Git Conventions

Branch Names

type/kebab-case-description

Types: feat/, fix/, chore/, docs/, refactor/, art/

Commit Messages

Conventional Commits:

type(scope): lowercase imperative description

Prefix	Purpose
feat:	New feature
fix:	Bug fix
chore:	Maintenance, dependencies
docs:	Documentation only
art:	Icons, theme, visual assets
refactor:	Code restructuring

Scopes: solver, sketcher, editing-context, toolbar, datums, silo, gears, sdk, breadcrumb, gui, assembly, ci, theme, or omitted.

PR Workflow

1. Create a branch from main: git checkout -b feat/my-feature main
2. Commit with conventional commit messages
3. Push and open a PR against main via Gitea (or tea pulls create)
4. CI runs automatically on PRs

Code Style

• C++: clang-format (.clang-format), clang-tidy (.clang-tidy)
• Python: black (100-char line length), pylint (.pylintrc)
• Pre-commit hooks: pre-commit install (runs clang-format, black, trailing-whitespace, etc.)

CI/CD

• Build: .gitea/workflows/build.yml — runs on pushes to main and on PRs
• Release: .gitea/workflows/release.yml — triggered by v* tags, builds AppImage and .deb
• Platform: Currently Linux x86_64 only in CI; other platforms have presets but no runners yet

Documentation

Document	Content
README.md	Project overview, installation, usage
CONTRIBUTING.md	Branch workflow, commit conventions, code style
docs/ARCHITECTURE.md	Bootstrap flow, addon lifecycle, source layout
docs/COMPONENTS.md	Feature inventory (Silo, origin, theme, icons)
docs/KNOWN_ISSUES.md	Known issues, incomplete features, next steps
docs/INTEGRATION_PLAN.md	5-layer architecture, phase status
docs/CI_CD.md	Build and release workflows
docs/KC_SPECIFICATION.md	.kc file format specification
docs/UPSTREAM.md	FreeCAD upstream merge strategy
docs/INTER_SOLVER.md	Assembly solver integration
docs/BOM_MERGE.md	BOM-Assembly bridge specification

The docs/src/ directory contains an mdBook site with detailed guides organized by topic (architecture, development, guide, reference, silo-server, solver).

Issue Tracker

Issues are tracked on Gitea at git.kindred-systems.com/kindred/create/issues. Use the tea CLI for local interaction:

tea issues              # List open issues
tea issues 123          # View issue #123 details
tea pulls create        # Create a PR

Known Issues and Pitfalls

1. Silo auth not production-hardened — LDAP/OIDC backends are coded but need infrastructure deployment
2. No unit tests for Silo FreeCAD commands or Go backend
3. Assembly solver datum handling is minimal — joints referencing datum planes/points may produce incorrect placement
4. Silo_BOM requires Silo-tracked document — unregistered documents show a warning with no registration path
5. QSS edits — only edit src/Gui/Stylesheets/KindredCreate.qss; the PreferencePacks copy is auto-generated
6. Archived addons — reference/ztools/ and reference/quicknav/ are archived source for reference only; they are not built or loaded