create/docs/REPOSITORY_STATE.md

Kindred Create Repository State Report

Generated: 2026-01-31 Branch: main Parent repo: create-0070 @ 364a7057ef Submodules:

• ztools @ 8d1f195 (ztools-0065, main)
• silo @ c778825 (silo-0062, main)

---

Recent Changes (This Session)

Assembly Solver Fix

• 610fd43 — PartDesign datum planes (including ZTools datums) now work correctly as joint references in Assembly. findPlacement() in src/Mod/Assembly/UtilsAssembly.py extracts geometry from PartDesign::Plane and PartDesign::Point objects instead of returning zero placements.

ZTools Bug Fixes

• 665bdb2 — Three fixes in the ztools submodule:
  • Removed int() wrapper from getStandardButtons() (Qt6/PySide6 compatibility — StandardButton enum is not int-castable).
  • Guarded _setup_ztools_viewprovider() against C++ ViewProviders that lack a Proxy attribute (PartDesign::Plane uses ViewProviderDatumPlane, pure C++).
  • Changed setEditorMode(prop, 2) to setPropertyStatus(prop, "Hidden") for persistent attachment property hiding across save/reload.

ZTools Parametric Datums via AttachExtension

• 2c716b4 — ZTools datum planes now leverage FreeCAD's built-in Part::AttachExtension for automatic parametric updates. Instead of MapMode = "Deactivated" with manual placement, each datum type maps to a vanilla MapMode (FlatFace, ThreePointsPlane, NormalToEdge, etc.) with appropriate AttachmentSupport and AttachmentOffset. Datums update automatically when source geometry changes on recompute.

Stylesheet Fixes (Uncommitted — Staged)

• Tree branch indicators: Created branch_closed.svg and branch_open.svg in images_dark-light/ with Catppuccin #cdd6f4 chevrons. Added QTreeView::branch image rules for expand/collapse states.
• Spinbox/combobox arrows: Synced all three QSS copies so the CSS border-triangle arrow fix (previously only in resources/preferences/) now applies at runtime via src/Gui/Stylesheets/KindredCreate.qss.
• Header clipping: Added min-height: 20px to QHeaderView::section.
• QSS sync: All four copies (resources/preferences/, src/Gui/Stylesheets/, src/Gui/PreferencePacks/, mods/ztools/CatppuccinMocha/) are now byte-identical. Merged dock widget padding and spreadsheet cell editor styling improvements that existed only in the Stylesheets copy.

ZTools-PartDesign Merge (Uncommitted — Staged)

• _ZToolsPartDesignManipulator in mods/ztools/ztools/InitGui.py uses Gui.addWorkbenchManipulator() to inject ZTools commands into PartDesign's C++ toolbars:
  • ZTools_DatumCreator + ZTools_DatumManager → "Part Design Helper Features"
  • ZTools_EnhancedPocket → "Part Design Modeling Features"
  • ZTools_RotatedLinearPattern → "Part Design Transformation Features"
  • Same commands also inserted into the Part Design menu after PartDesign_Boolean.

Silo Enhancements (Uncommitted — Staged)

• File menu integration: SiloMenuManipulator in src/Mod/Create/InitGui.py injects Silo_New, Silo_Open, Silo_Save, Silo_Commit, Silo_Pull, Silo_Push, and Silo_BOM into the File menu across all workbenches.
• Toolbar toggle: Silo_ToggleMode checkable command swaps Ctrl+O/S/N between standard FreeCAD file commands and Silo equivalents. Appended to the global File toolbar via the manipulator.
• SSL certificate browsing: Settings dialog now includes a file browser for custom CA certificates (SslCertPath preference). _get_ssl_context() loads the custom cert before system CAs.
• BOM integration: Upstream BOM feature (Silo_BOM command with tabbed dialog — BOM + Where Used) merged with local changes and added to the Create File menu manipulator.

---

Architecture Overview

create-0070/                          Kindred Create (FreeCAD 1.0+ fork)
├── src/
│   ├── Mod/
│   │   ├── Assembly/                 Assembly solver (OndselSolver)
│   │   ├── PartDesign/              Part modeling (C++ workbench)
│   │   ├── Sketcher/                2D constraint sketcher
│   │   ├── Create/                  Kindred bootstrap module (Python)
│   │   │   └── InitGui.py          Loads ztools+silo, installs manipulators
│   │   └── ...                      Other FreeCAD modules
│   └── Gui/
│       ├── Stylesheets/             QSS themes + arrow/branch SVGs
│       ├── PreferencePacks/         Preference pack bundles
│       └── WorkbenchManipulatorPython.cpp  Menu/toolbar injection API
├── mods/
│   ├── ztools/                      [submodule] ztools-0065
│   │   └── ztools/
│   │       ├── InitGui.py           ZToolsWorkbench + PartDesign manipulator
│   │       └── ztools/
│   │           ├── commands/        Datum, pattern, pocket, assembly, spreadsheet
│   │           ├── datums/core.py   Datum creation with AttachExtension
│   │           └── resources/       Icons, theme utilities
│   └── silo/                        [submodule] silo-0062
│       └── pkg/freecad/
│           ├── InitGui.py           SiloWorkbench
│           └── silo_commands.py     12 commands + SiloClient API
└── resources/
    └── preferences/KindredCreate/   Canonical QSS + preference pack

Integration Flow

FreeCAD startup
  └─ src/Mod/Create/InitGui.py exec()
       ├─ exec(mods/ztools/ztools/InitGui.py)
       │    ├─ registers ZToolsWorkbench
       │    └─ installs _ZToolsPartDesignManipulator (global)
       ├─ exec(mods/silo/pkg/freecad/InitGui.py)
       │    └─ registers SiloWorkbench
       └─ QTimer.singleShot(2000):
            ├─ _setup_silo_menu()
            │    └─ installs SiloMenuManipulator (global)
            │         ├─ modifyMenuBar: Silo commands in File menu
            │         └─ modifyToolBars: Silo_ToggleMode in File toolbar
            ├─ _check_silo_first_start()
            └─ _setup_silo_activity_panel()

---

Submodule Status

ztools (ztools-0065)

Commit	Description
8d1f195	Add PartDesign WorkbenchManipulator and sync Catppuccin theme
005348b	Leverage FreeCAD AttachExtension for parametric datum updates
0e95d1c	Fix Qt6 StandardButton TypeError and C++ ViewProvider Proxy errors
98bd444	Fix workbench init and spreadsheet syntax errors

Custom commands: 9 registered

• ZTools_DatumCreator, ZTools_DatumManager
• ZTools_RotatedLinearPattern
• ZTools_EnhancedPocket
• ZTools_AssemblyLinearPattern, ZTools_AssemblyPolarPattern
• ZTools_SpreadsheetStyle{Bold,Italic,Underline}, ZTools_SpreadsheetAlign{Left,Center,Right}, ZTools_Spreadsheet{BgColor,TextColor,QuickAlias}

Datum types supported: offset_from_face, offset_from_plane, midplane, 3_points, normal_to_edge, angled, tangent_to_cylinder

silo (silo-0062)

Commit	Description
c778825	Add Silo mode toggle, SSL cert browsing, and BOM menu integration
8c06899	(upstream) Various fixes
bce7d5a	Add BOM handling and routes to API and web UI
3a79d89	feat: add BOM system with API, database repository, and FreeCAD command
8e44ed2	Fix SIGSEGV: defer document open after dialog close

FreeCAD commands: 12 registered

• Silo_Open, Silo_New, Silo_Save, Silo_Commit
• Silo_Pull, Silo_Push, Silo_Info, Silo_BOM
• Silo_TagProjects, Silo_Rollback, Silo_SetStatus
• Silo_Settings, Silo_ToggleMode

API surface: 38 REST routes covering items, revisions, files, BOM, projects, schemas, and Odoo integration stubs. See mods/silo/docs/REPOSITORY_STATUS.md for full route table.

BOM API methods (new):

• get_bom(), get_bom_expanded(), get_bom_where_used()
• add_bom_entry(), update_bom_entry(), delete_bom_entry()

---

Potential Issues

Critical

1. Three QSS copies can drift again. The canonical source is resources/preferences/KindredCreate/KindredCreate.qss. The other copies (src/Gui/Stylesheets/, src/Gui/PreferencePacks/, mods/ztools/CatppuccinMocha/) must be kept in sync manually. Consider a build step or symlinks to eliminate duplication.

2. WorkbenchManipulator command registration timing. The _ZToolsPartDesignManipulator appends commands by name (e.g. ZTools_DatumCreator). If the ZTools workbench has not been initialized (first activation) when the user switches to PartDesign, the commands may not be registered yet. The Create/InitGui.py exec() loads the workbench class but Initialize() only runs on first activation. The manipulator API tolerates missing commands silently (toolbar append returns without error), but the buttons won't appear until ZTools initializes. Mitigation: force-activate ZToolsWorkbench during Create module load, or defer manipulator installation.

3. Silo toggle mode shortcut persistence. _swap_shortcuts() stores original shortcuts in a module-level dict (_original_shortcuts). If FreeCAD crashes with Silo mode ON, the original shortcuts are lost and standard commands will have no keyboard shortcuts on next launch. Consider persisting original shortcuts to preferences.

High

4. Silo has no authentication. All API endpoints are publicly accessible. Required before multi-user deployment. See mods/silo/docs/REPOSITORY_STATUS.md for full list.

5. No unit tests for silo FreeCAD commands or ztools. Python code has zero test coverage. The Go backend also lacks tests per the silo status report.

6. Assembly solver findPlacement() geometry extraction is minimal. The fix at UtilsAssembly.py:1006 extracts placement from obj.Shape.Faces[0] for PartDesign::Plane. This works for planar datums but does not handle edge cases like empty shapes or non-planar datum objects.

Medium

7. Silo_BOM depends on get_tracked_object() which looks for a SiloPartNumber property on document objects. Documents not registered with Silo show a warning dialog. The UX could be improved with a one-click registration flow from the BOM dialog.

8. _ZToolsPartDesignManipulator.modifyMenuBar() inserts after PartDesign_Boolean. If upstream FreeCAD renames or removes this command, the menu insertions silently fail. The toolbar appends (by toolbar name) are more robust.

9. ZTools plane_tangent_to_cylinder falls back to manual placement because the TangentPlane MapMode requires a vertex reference not currently collected by the UI. This is the only datum type that does not benefit from automatic parametric updates.

10. Silo delete_bom_entry() uses raw urllib.request instead of the _request() helper method on SiloClient. This bypasses error normalization. Should be refactored to use self._request("DELETE", ...).

---

Feature Stubs and TODOs

From silo REPOSITORY_STATUS

Feature	Status	Location
Odoo ERP integration	Stub (returns "not yet implemented")	internal/odoo/
Part number date segments	Broken (formatDate() returns error)	internal/partnum/generator.go:102
Location/Inventory APIs	Tables exist, no handlers	migrations/001_initial.sql
File locking	Not implemented	—
Authentication/Authorization	Not implemented	—
CSRF protection	Not implemented	Web UI only
CSV import transaction rollback	Not implemented	bom_handlers.go

From ztools

Feature	Status	Location
Tangent-to-cylinder attachment	Manual fallback (no vertex ref)	datums/core.py
Angled datum live editing	AttachmentOffset rotation not updated in panel	datum_viewprovider.py
Assembly pattern undo support	Not implemented	assembly_pattern_commands.py

From Create integration plan

Phase	Feature	Status
1	Addon auto-loading	Done (src/Mod/Create/InitGui.py)
2	Enhanced Pocket as C++ feature	Not started
3	Datum C++ helpers	Not started (Python AttachExtension approach used instead)
4	Theme system refinement	Partially done (QSS synced, not moved to Create module)
5	Silo deep integration	Done (manipulator-based menu/toolbar injection)
6	Build system integration	Not started

---

File Change Summary (Uncommitted)

Parent repo (create-0070)

File	Change
resources/preferences/KindredCreate/KindredCreate.qss	Branch indicators, header min-height, dock/actiongroup improvements, spreadsheet cell editor
src/Gui/Stylesheets/KindredCreate.qss	Synced with canonical
src/Gui/PreferencePacks/KindredCreate/KindredCreate.qss	Synced with canonical
src/Gui/Stylesheets/images_dark-light/branch_closed.svg	New: right-pointing chevron
src/Gui/Stylesheets/images_dark-light/branch_open.svg	New: down-pointing chevron
src/Mod/Create/InitGui.py	Expanded SiloMenuManipulator (BOM, full commands, toolbar toggle)
mods/silo	Submodule pointer updated
mods/ztools	Submodule pointer updated

ztools submodule (committed + pushed)

File	Change
ztools/InitGui.py	Added _ZToolsPartDesignManipulator
CatppuccinMocha/CatppuccinMocha.qss	Synced with canonical KindredCreate.qss

silo submodule (committed + pushed)

File	Change
pkg/freecad/silo_commands.py	SSL cert browsing, Silo_ToggleMode, BOM merge
pkg/freecad/InitGui.py	Added Silo_ToggleMode to toolbar

---

Silo Integration Path

Based on mods/silo/docs/REPOSITORY_STATUS.md and the existing docs/INTEGRATION_PLAN.md, the integration path forward is:

Completed

• Addon auto-loading via src/Mod/Create/InitGui.py
• Global File menu injection via WorkbenchManipulator
• Toolbar toggle for Silo mode (shortcut swapping)
• SSL certificate configuration for internal CAs
• BOM command integrated into File menu

Next Steps

1. Authentication — LDAP/FreeIPA integration for multi-user. Silo server needs auth middleware; FreeCAD client needs credential storage in preferences.
2. BOM-Assembly bridge — Auto-populate Silo BOM from FreeCAD Assembly component links. When a user saves an assembly, extract child part numbers from Assembly_InsertLink objects and sync to Silo BOM.
3. File locking — Pessimistic locks on checkout (Silo_Open) to prevent concurrent edits. Requires server-side lock table and client-side lock-status display.
4. Status bar integration — Show current Silo item part number, revision, and sync status in FreeCAD's status bar. Use FreeCADGui.getMainWindow().statusBar().
5. Build system — CMake install rules for mods/ submodules so .deb packages include ztools and silo without manual intervention.