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, two addon command sets (ztools and Silo), 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++)
│   │   ├── 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
│   │       ├── Init.py         Console bootstrap — loads addons
│   │       ├── InitGui.py      GUI bootstrap — loads addons, Silo setup, update checker
│   │       ├── addon_loader.py Manifest-driven loader with dependency resolution
│   │       └── kc_format.py    .kc file format preservation
│   └── 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)
│   ├── ztools/                [submodule] Command provider (priority 50)
│   ├── silo/                  [submodule] PLM workbench (priority 60)
│   ├── solver/                [submodule] Assembly solver research (GNN-based)
│   └── quicknav/              [submodule] 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.

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:

• FreeCADGui.registerEditingContext() — register a new context
• FreeCADGui.registerEditingOverlay() — conditional toolbar overlay
• FreeCADGui.injectEditingCommands() — add commands to existing contexts
• FreeCADGui.currentEditingContext() — query active context
• FreeCADGui.refreshEditingContext() — force re-evaluation

Addon Loading

Addons in mods/ are loaded by src/Mod/Create/addon_loader.py. Each addon provides a package.xml with <kindred> extensions declaring version bounds, load priority, and dependencies. The loader resolves via topological sort: sdk (0) -> ztools (50) -> silo (60).

A <workbench> tag in package.xml is required for InitGui.py to be loaded, even if no actual workbench is registered.

Deferred Initialization

GUI setup uses QTimer.singleShot with staggered delays:

• 500ms: .kc file format registration
• 1500ms: Silo origin registration
• 2000ms: Auth dock + ztools commands
• 2500ms: Silo overlay
• 3000ms: Silo first-start check
• 4000ms: Activity panel
• 10000ms: Update checker

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).

Submodules

Path	Repository	Branch	Purpose
mods/ztools	git.kindred-systems.com/forbes/ztools	main	Extended PartDesign/Assembly/Spreadsheet tools
mods/silo	git.kindred-systems.com/kindred/silo-mod	main	PLM workbench (includes silo-client submodule)
mods/solver	git.kindred-systems.com/kindred/solver	main	Assembly solver research (GNN-based)
mods/quicknav	git.kindred-systems.com/kindred/quicknav	—	Navigation addon
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

ztools (mods/ztools/)

Command provider (NOT a workbench). Injects tools into PartDesign, Assembly, and Spreadsheet contexts via _ZToolsManipulator (WorkbenchManipulator) and injectEditingCommands().

Commands: ZTools_DatumCreator, ZTools_EnhancedPocket, ZTools_RotatedLinearPattern, ZTools_AssemblyLinearPattern, ZTools_AssemblyPolarPattern, spreadsheet formatting (Bold, Italic, Underline, alignment, colors, QuickAlias).

Source: mods/ztools/ztools/ztools/commands/ (note the double ztools nesting).

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.

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

SDK (mods/sdk/)

Stable API contract for addons. Provides wrappers for editing contexts, theme tokens (Catppuccin Mocha YAML palette), FileOrigin registration, and deferred dock panels. Addons should use kindred_sdk.* instead of FreeCADGui.* internals where possible.

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)
• 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, ztools, silo, breadcrumb, gui, assembly, ci, theme, quicknav, 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 (ztools, 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 ztools/Silo FreeCAD commands or Go backend
3. Assembly solver datum handling is minimal — joints referencing datum planes/points may produce incorrect placement
4. PartDesign menu insertion fragility — _ZToolsPartDesignManipulator.modifyMenuBar() inserts after PartDesign_Boolean; upstream renames break silently
5. Silo_BOM requires Silo-tracked document — unregistered documents show a warning with no registration path
6. QSS edits — only edit src/Gui/Stylesheets/KindredCreate.qss; the PreferencePacks copy is auto-generated