Merge pull request 'docs: update CLAUDE.md with current repository context' (#378) from docs/claude-md-update into main

Reviewed-on: #378

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## 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 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
@@ -33,6 +33,14 @@ create/
 │   ├── 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)
@@ -44,20 +52,30 @@ create/
 │   │   └── 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, Silo setup, update checker
+│   │       ├── 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
+│   │       ├── 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)
-│   ├── ztools/                [submodule] Command provider (priority 50)
+│   ├── 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 (GNN-based)
+│   └── solver/                [submodule] Assembly solver research (priority 10)
-│   └── quicknav/              [submodule] Navigation addon
+├── 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/)
@@ -110,6 +128,19 @@ if (obj->isDerivedFrom(type)) { ... }
 
 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.
@@ -122,42 +153,49 @@ The `EditingContextResolver` singleton (`src/Gui/EditingContext.h/.cpp`) drives
 
 Built-in contexts: `sketcher.edit`, `assembly.edit`, `partdesign.feature`, `partdesign.body`, `assembly.idle`, `spreadsheet`, `empty_document`, `no_document`.
 
-Python API:
+Python API (prefer `kindred_sdk` wrappers over direct `FreeCADGui` calls):
-- `FreeCADGui.registerEditingContext()` — register a new context
+- `kindred_sdk.register_context()` — register a new context
-- `FreeCADGui.registerEditingOverlay()` — conditional toolbar overlay
+- `kindred_sdk.register_overlay()` — conditional toolbar overlay
-- `FreeCADGui.injectEditingCommands()` — add commands to existing contexts
+- `kindred_sdk.inject_commands()` — add commands to existing contexts
-- `FreeCADGui.currentEditingContext()` — query active context
+- `kindred_sdk.current_context()` — query active context
-- `FreeCADGui.refreshEditingContext()` — force re-evaluation
+- `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` with `<kindred>` extensions declaring version bounds, load priority, and dependencies. The loader resolves via topological sort: **sdk** (0) -> **ztools** (50) -> **silo** (60).
+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)`.
 
-A `<workbench>` tag in `package.xml` is required for `InitGui.py` to be loaded, even if no actual workbench is registered.
+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:
+GUI setup uses `QTimer.singleShot` with staggered delays. Create core (`src/Mod/Create/InitGui.py`) handles:
 - 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
 
+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/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/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) |
-| `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 |
@@ -176,29 +214,53 @@ Initialize all submodules: `git submodule update --init --recursive`
 
 ## Key Addon Modules
 
-### ztools (`mods/ztools/`)
+### SDK (`mods/sdk/`)
 
-Command provider (NOT a workbench). Injects tools into PartDesign, Assembly, and Spreadsheet contexts via `_ZToolsManipulator` (WorkbenchManipulator) and `injectEditingCommands()`.
+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()`
 
-Commands: `ZTools_DatumCreator`, `ZTools_EnhancedPocket`, `ZTools_RotatedLinearPattern`, `ZTools_AssemblyLinearPattern`, `ZTools_AssemblyPolarPattern`, spreadsheet formatting (Bold, Italic, Underline, alignment, colors, QuickAlias).
+Addons should use `kindred_sdk.*` instead of `FreeCADGui.*` internals where possible.
 
-Source: `mods/ztools/ztools/ztools/commands/` (note the double `ztools` nesting).
+### 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.
 
-Silo origin detection: `silo_origin.py:ownsDocument()` checks for `SiloItemId`/`SiloPartNumber` properties on the active document.
+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`.
 
-### SDK (`mods/sdk/`)
+Silo origin detection: `silo_origin.py:ownsDocument()` checks for `SiloItemId`/`SiloPartNumber` properties on the active document. Origin registered via `kindred_sdk.register_origin()`.
 
-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.
+### 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
@@ -226,7 +288,7 @@ type(scope): lowercase imperative description
 | `art:` | Icons, theme, visual assets |
 | `refactor:` | Code restructuring |
 
-Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `ztools`, `silo`, `breadcrumb`, `gui`, `assembly`, `ci`, `theme`, `quicknav`, or omitted.
+Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `datums`, `silo`, `gears`, `sdk`, `breadcrumb`, `gui`, `assembly`, `ci`, `theme`, or omitted.
 
 ### PR Workflow
 
@@ -254,7 +316,7 @@ Scopes: `solver`, `sketcher`, `editing-context`, `toolbar`, `ztools`, `silo`, `b
 | `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/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 |
@@ -278,8 +340,8 @@ 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
+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. **PartDesign menu insertion fragility** — `_ZToolsPartDesignManipulator.modifyMenuBar()` inserts after `PartDesign_Boolean`; upstream renames break silently
+4. **`Silo_BOM` requires Silo-tracked document** — unregistered documents show a warning with no registration path
-5. **`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. **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