Schema added

docs/NEXT_PHASES.md

@@ -0,0 +1,29 @@
+# CAD/BIM Library Next Phases
+
+## Phase 1: Cleanup and classification
+
+Create a safe cleaned library outside the source repository. Copy only selected BIM-relevant assets, normalize folder names, classify file types, and generate first-pass `template.json` files plus metadata reports.
+
+## Phase 2: Parameter schema system
+
+Enrich cleaned `template.json` metadata with reusable parameter definitions, element-type schemas, validation rules, schema readiness flags, and floating-toolbar group hints. This phase prepares data for a future UI but does not edit geometry.
+
+## Phase 3: Geometry generator system
+
+Create backend placeholder generators that turn enriched template parameters into neutral mesh geometry, OBJ previews, STL previews, and generator manifests. This proves the parameter-to-geometry contract before building UI or real-time editing.
+
+## Phase 4: Floating parameter toolbar UI
+
+Create the floating parameter toolbar after stable schemas and generator interfaces exist. The toolbar should read Phase 2 toolbar groups, edit schema-backed parameters, and call Phase 3 generator APIs rather than directly mutating static reference meshes.
+
+## Phase 5: Real-time regeneration and viewport update
+
+Connect toolbar edits to real-time geometry regeneration, validation, preview updates, and viewport refresh. This phase should include performance testing and fallback behavior for assets that remain static references.
+
+## Phase 6: Save/export parametric project data
+
+Persist schema-backed parameters, generator references, user edits, and export mappings so projects can be reopened, versioned, and exported without losing parametric intent.
+
+## Phase 7: Advanced CAD kernel / FreeCAD / OpenCASCADE integration
+
+Replace or augment placeholder mesh generators with robust CAD-kernel-backed generation for production solids, booleans, constraints, IFC/BIM semantics, and high-quality import/export workflows.

docs/PHASE_1_LIBRARY_CLEANUP.md

@@ -0,0 +1,108 @@
+# Phase 1 CAD/BIM Library Cleanup
+
+Phase 1 creates a safe, curated CAD/BIM asset library from the broader FreeCAD-library repository. The goal is cleanup and classification only: no CAD editor, floating toolbar, parametric engine, or real-time 3D editing is built in this phase.
+
+## Why this cleanup exists
+
+The upstream library contains many useful BIM-adjacent objects, but it also includes electronics, robotics, sports, mechanical, PCB, and general-purpose models. A CAD/BIM product needs a smaller, predictable structure organized around building elements, MEP parts, site assets, and metadata that later systems can read.
+
+The cleanup script copies selected BIM-relevant files into a separate output folder and generates metadata beside those copied files. It intentionally does **not** modify the source library.
+
+## Safety model
+
+`tools/cleanup_phase1.py` is non-destructive:
+
+- it does not delete original files;
+- it does not move original files;
+- it does not overwrite source files;
+- it refuses to place the cleaned output inside the source repository;
+- it copies only files that match Phase 1 BIM category and file-type rules.
+
+Generated cleaned output should live outside the repository, for example `/tmp/cad_bim_library_cleaned` or `../cad_bim_library_cleaned`.
+
+## Dry-run command
+
+Use dry-run first to inspect what would be copied without creating output files:
+
+```bash
+python tools/cleanup_phase1.py --source . --output ../cad_bim_library_cleaned --dry-run
+```
+
+A dry-run prints totals for files scanned, BIM-relevant files that would be copied, asset folders that would be created, backup files detected, and PCB/Gerber files detected.
+
+## Actual cleanup command
+
+After dry-run succeeds, run the actual copy:
+
+```bash
+python tools/cleanup_phase1.py --source . --output ../cad_bim_library_cleaned
+```
+
+To create an archive placeholder for future non-BIM asset workflows, add:
+
+```bash
+python tools/cleanup_phase1.py --source . --output ../cad_bim_library_cleaned --include-archive
+```
+
+To focus on one cleaned category while testing, add a category such as:
+
+```bash
+python tools/cleanup_phase1.py --source . --output ../cad_bim_library_cleaned --limit-category architecture.doors
+```
+
+## Cleaned folder meanings
+
+The cleaned output has these top-level areas:
+
+- `00_metadata/` contains reports, file rules, and `library_index.json`.
+- `architecture/` contains doors, windows, beams, roof assets, construction blocks, bathroom/kitchen fixtures, furniture, foundations, and architecture-related symbols.
+- `mep/` contains HVAC ducts, HVAC pipes, plumbing pipes, hydro equipment, and electrical equipment relevant to building systems.
+- `site/` contains topography and vegetation/site assets.
+- `archive_non_bim/` is created only when `--include-archive` is passed. Phase 1 reports non-BIM candidates but does not blindly copy the entire archive.
+
+Asset folders use normalized `snake_case` names so downstream software can depend on stable paths. For example, a source group like:
+
+```text
+Architectural Parts/Doors/Wood/Single door with trims.FCStd
+Architectural Parts/Doors/Wood/Single door with trims.step
+Architectural Parts/Doors/Wood/Single door with trims.stl
+```
+
+becomes:
+
+```text
+architecture/doors/wood/single_door_with_trims/
+  source.FCStd
+  reference.step
+  preview.stl
+  template.json
+```
+
+## Static reference geometry
+
+STEP, STL, BREP, image, and documentation files are useful as geometry references, previews, or documentation, but they are not treated as live parametric generators in Phase 1. STEP files can preserve exchange geometry, and STL files can provide preview meshes, but neither guarantees editable CAD/BIM parameters such as width, height, swing direction, glazing type, or duct bend angle.
+
+## FreeCAD source files
+
+`.FCStd` and `.fcstd` files are treated as possible parametric sources because they may contain FreeCAD-native model data. They are still marked as `static_reference` in Phase 1 because the cleanup script does not inspect constraints, object history, sketches, or generator logic. `parametricSourceAvailable` means a native source exists, not that real-time editing is already implemented.
+
+## Generated metadata
+
+Each cleaned asset folder receives a `template.json` with:
+
+- an asset ID;
+- element type;
+- cleaned category;
+- display name;
+- original source path;
+- copied source file names;
+- file type groups;
+- editability status;
+- placeholder parameters;
+- notes explaining that generator work is still required.
+
+`00_metadata/library_index.json` lists every cleaned asset for product ingestion. Reports in `00_metadata/` summarize cleanup results, missing templates, excluded non-BIM candidates, and file rules.
+
+## Preparing for a later floating parameter toolbar
+
+Phase 1 provides consistent asset IDs, categories, templates, and placeholder parameter names. That structure lets Phase 2 refine parameter schemas before Phase 3 creates geometry generators. Only after generator logic exists should a floating parameter toolbar attempt real-time model regeneration.

docs/PHASE_2_PARAMETER_SCHEMA_SYSTEM.md

@@ -0,0 +1,98 @@
+# Phase 2 Parameter Schema System
+
+Phase 2 makes the cleaned CAD/BIM library metadata more structured and ready for future parameter-driven editing. It works on the cleaned output from Phase 1, not on the original FreeCAD-library source assets.
+
+This phase still does **not** build a CAD editor, floating toolbar UI, real-time modelling engine, or geometry generator.
+
+## How Phase 2 connects to Phase 1
+
+Phase 1 copies selected BIM-relevant assets into a separate cleaned folder and creates one `template.json` for each cleaned asset. Those first templates contain useful starting metadata, but their parameters are intentionally broad placeholders.
+
+Phase 2 reads those `template.json` files and enriches them with consistent parameter definitions, validation metadata, toolbar group hints, schema status, and reports. The original `.FCStd`, `.step`, `.stl`, `.brep`, image, and documentation files are not edited.
+
+## What the Phase 2 script does
+
+`tools/parameter_schema_phase2.py` scans a cleaned library folder for asset-level `template.json` files. For each template it:
+
+- loads the existing template metadata;
+- infers a standard BIM element type when needed;
+- compares parameters against `element_type_schemas.json`;
+- adds missing required parameters;
+- enriches parameters from `parameter_catalog.json`;
+- adds validation metadata;
+- adds floating-toolbar grouping metadata for a future UI;
+- normalizes `editability.status` to an allowed value;
+- preserves existing data wherever possible;
+- writes an updated template only when `--write` is passed.
+
+## Dry-run command
+
+Run dry-run first to validate and preview enrichment without updating templates:
+
+```bash
+python tools/parameter_schema_phase2.py --library-root /tmp/cad_bim_library_cleaned --dry-run
+```
+
+Dry-run writes Phase 2 reports by default to:
+
+```text
+/tmp/cad_bim_library_cleaned/00_metadata/phase2_schema_reports/
+```
+
+## Apply schema enrichment
+
+After reviewing dry-run output, apply enrichment with:
+
+```bash
+python tools/parameter_schema_phase2.py --library-root /tmp/cad_bim_library_cleaned --write --backup
+```
+
+`--backup` creates `.bak` copies of `template.json` files before writing updated metadata. This backup affects only cleaned metadata files in the Phase 1 output folder, not the original FreeCAD source assets.
+
+To process one category while testing, use:
+
+```bash
+python tools/parameter_schema_phase2.py --library-root /tmp/cad_bim_library_cleaned --dry-run --limit-category architecture.doors
+```
+
+## Schema configuration files
+
+The schema configuration lives in `schemas/parameter_schema/`.
+
+### `parameter_catalog.json`
+
+`parameter_catalog.json` is the master dictionary of reusable parameters. Each parameter includes its name, label, description, type, unit, default value, min/max rules, options, UI-control hint, toolbar group, and validation metadata.
+
+Examples include `width`, `height`, `thickness`, `swingDirection`, `openingType`, `material`, `fireRating`, `flowDirection`, `ductShape`, `manufacturer`, and `sourceUrl`.
+
+### `element_type_schemas.json`
+
+`element_type_schemas.json` maps BIM element types to required parameters, optional parameters, allowed file types, and toolbar groups. For example, `Door` requires `width`, `height`, and `thickness`, while `Pipe` requires `diameter` and `length`.
+
+### `validation_rules.json`
+
+`validation_rules.json` documents the general rules for valid templates: required top-level fields, known parameter names, required parameters by element type, naming conventions, category dot notation, and allowed editability statuses.
+
+## Phase 2 reports
+
+Reports are written under `00_metadata/phase2_schema_reports/` unless `--report-dir` is supplied:
+
+- `phase2_schema_report.md` summarizes scanned templates, valid templates, enriched templates, missing required parameters, unsupported assets, custom parameters, processed categories, limitations, and the next recommended step.
+- `phase2_validation_report.csv` lists validation issues or success rows per asset.
+- `phase2_parameter_coverage.csv` summarizes parameter coverage by element type.
+- `phase2_toolbar_groups.json` aggregates toolbar group definitions by element type.
+- `phase2_unsupported_assets.csv` lists assets that could not be mapped to a useful schema.
+
+## How a future floating toolbar will use this schema
+
+The enriched templates include a `toolbar` block with `floating_parameter_panel` mode and grouped parameter names. A later UI can read these groups to decide which controls to show for dimensions, operation, materials, MEP settings, classification, or metadata.
+
+However, Phase 2 only prepares metadata for that UI. It does not create the UI itself.
+
+## Why STEP/STL files are still not truly editable
+
+STEP and STL files can describe reference geometry or preview meshes, but they do not automatically expose product parameters such as door swing direction, pipe schedule, duct shape, or window glazing type. Phase 2 can add clean parameter metadata beside those files, but it cannot make a static mesh or exchange file regenerate from parameter changes.
+
+## Why Phase 3 geometry generators are still required
+
+A future editor needs generator logic that consumes parameters and creates or updates real geometry. Phase 3 should define and implement those generators. Only after generator APIs exist should Phase 4 build the floating toolbar UI and Phase 5 connect toolbar edits to real-time viewport regeneration.

docs/PHASE_3_GEOMETRY_GENERATOR_SYSTEM.md

@@ -0,0 +1,92 @@
+# Phase 3 Geometry Generator System
+
+Phase 3 creates a backend generator framework that turns enriched `template.json` metadata into simple parametric placeholder geometry. It proves this workflow:
+
+```text
+template.json parameters -> generator -> geometry output
+```
+
+This phase is not the final CAD kernel, not a floating toolbar UI, and not real-time viewport editing.
+
+## How Phase 3 depends on Phase 1 and Phase 2
+
+Phase 1 creates a cleaned BIM-oriented library outside the original FreeCAD-library repository. Phase 2 enriches each cleaned asset's `template.json` with consistent parameters and toolbar-ready metadata. Phase 3 reads those enriched templates and generates simple geometry from their parameters.
+
+The original FreeCAD source assets are not modified. Phase 3 does not edit `.FCStd`, `.step`, `.stl`, `.brep`, images, or documentation files.
+
+## Why generated geometry is placeholder geometry
+
+The goal is not to perfectly recreate the original FreeCAD assets. Instead, each element type gets a simple standard-library mesh:
+
+- doors become a panel and frame;
+- windows become a frame and glass panel;
+- beams become a box or simple I-beam approximation;
+- roofs become a sloped slab;
+- construction blocks become rectangular blocks;
+- pipes and ducts become cylinder-like or rectangular placeholder meshes;
+- furniture, fixtures, foundations, vegetation, and generic BIM objects become simple representative forms.
+
+This creates a safe backend contract for future UI work while keeping expectations clear: these meshes are not production CAD geometry.
+
+## Dry-run command
+
+Use dry-run to scan templates and write reports without writing geometry files:
+
+```bash
+python tools/geometry_generator_phase3.py --library-root /tmp/cad_bim_library_cleaned --output /tmp/cad_bim_generated_geometry --dry-run
+```
+
+## Generate geometry
+
+Generate all supported output formats with:
+
+```bash
+python tools/geometry_generator_phase3.py --library-root /tmp/cad_bim_library_cleaned --output /tmp/cad_bim_generated_geometry --write
+```
+
+Generate only one element type:
+
+```bash
+python tools/geometry_generator_phase3.py --library-root /tmp/cad_bim_library_cleaned --output /tmp/cad_bim_generated_geometry --write --limit-element-type Door
+```
+
+Generate only one asset:
+
+```bash
+python tools/geometry_generator_phase3.py --library-root /tmp/cad_bim_library_cleaned --output /tmp/cad_bim_generated_geometry --write --asset-id door_wood_single_door_with_trims
+```
+
+Use `--format json`, `--format obj`, `--format stl`, or `--format all` to choose outputs.
+
+## Output files
+
+Each generated asset folder can contain:
+
+- `geometry.json`: neutral mesh representation with asset id, element type, category, units, parameters used, vertices, faces, and generator metadata.
+- `preview.obj`: Wavefront OBJ preview mesh.
+- `preview.stl`: ASCII STL preview mesh.
+- `generator_manifest.json`: manifest explaining which generator ran, which template was used, which outputs were written, and the known limitations.
+
+Reports are written to `<output>/00_reports/` by default:
+
+- `phase3_generation_report.md`
+- `phase3_generation_report.csv`
+- `phase3_unsupported_assets.csv`
+- `phase3_generator_coverage.csv`
+- `phase3_generator_registry.json`
+
+## How a future floating toolbar will use this system
+
+A Phase 4 toolbar can edit schema-backed parameters from the enriched templates and then call these generator classes to regenerate placeholder geometry. Phase 5 can connect that regeneration loop to a viewport. Later phases can replace placeholder mesh generation with production-grade CAD-kernel operations.
+
+## Limitations
+
+- Placeholder geometry only.
+- No original FreeCAD, STEP, STL, BREP, or image assets are modified.
+- No dimensions are reverse-engineered from source CAD files.
+- OBJ and STL outputs are preview meshes, not authoritative BIM/CAD models.
+- Advanced constraints, boolean operations, openings, connectors, and parametric histories remain future work.
+
+## What Phase 4 should do next
+
+Phase 4 should build the floating parameter toolbar UI that reads Phase 2 schema metadata and calls Phase 3 generators through a stable backend interface. The UI should still communicate clearly when an asset is placeholder-only versus backed by a production generator.

docs/PHASE_4_FLOATING_PARAMETER_TOOLBAR.md

@@ -0,0 +1,59 @@
+# Phase 4 Floating Parameter Toolbar Prototype
+
+Phase 4 creates a zero-build browser prototype and Python integration layer for editing schema-backed BIM parameters. It proves that a cleaned/enriched `template.json` can become a floating editable toolbar, validated object state, preview drawing, and exported JSON.
+
+## How it depends on earlier phases
+
+- Phase 1 creates the cleaned BIM library and first `template.json` files.
+- Phase 2 enriches templates with parameters, validation metadata, and toolbar groups.
+- Phase 3 can optionally provide generated placeholder geometry links for preview/export context.
+
+Phase 4 still does not edit `.FCStd`, `.step`, `.stl`, `.brep`, image, or source CAD files.
+
+## Why this is still a prototype
+
+The UI uses plain HTML, CSS, JavaScript, and a simple canvas preview. It is meant to validate workflow and state management before investing in a production CAD viewport or OpenCASCADE/FreeCAD kernel integration.
+
+## Dry-run
+
+```bash
+python tools/floating_toolbar_phase4.py --library-root /tmp/cad_bim_library_cleaned --output /tmp/cad_bim_toolbar_demo --dry-run
+```
+
+Dry-run scans templates and writes reports only.
+
+## Generate toolbar demo data
+
+```bash
+python tools/floating_toolbar_phase4.py --library-root /tmp/cad_bim_library_cleaned --generated-geometry-root /tmp/cad_bim_generated_geometry --output /tmp/cad_bim_toolbar_demo --write
+```
+
+This writes `assets.json`, `toolbar_config.json`, `object_instances.json`, `geometry_links.json`, reports, and a copy of the static UI under `/tmp/cad_bim_toolbar_demo/ui/`.
+
+## Open the UI
+
+Open this file in a browser:
+
+```text
+/tmp/cad_bim_toolbar_demo/ui/index.html
+```
+
+Or run a local server:
+
+```bash
+python tools/floating_toolbar_phase4.py --output /tmp/cad_bim_toolbar_demo --serve --port 8765
+```
+
+Then open `http://localhost:8765/ui/index.html`.
+
+## How the floating toolbar works
+
+When an asset is selected, the UI creates an object instance with parameters initialized from template defaults or Phase 3 fallback defaults. It builds toolbar groups from `template.toolbar.groups`, falling back to each parameter's `toolbarGroup`. Number, select, checkbox, text, textarea, and color controls are generated dynamically.
+
+## Validation and preview updates
+
+Number inputs validate min/max and positive rules inline. Valid changes update the object-state JSON and redraw a simplified 2.5D canvas preview immediately after a short debounce.
+
+## What Phase 5 should do next
+
+Phase 5 should connect this state and toolbar workflow to real-time geometry regeneration and viewport integration. Later phases can replace placeholder preview drawing with CAD-kernel-backed model updates.

generators/__init__.py

@@ -0,0 +1,4 @@
+"""Phase 3 placeholder geometry generators."""
+from .registry import GENERATOR_REGISTRY, get_generator, registry_summary
+
+__all__ = ["GENERATOR_REGISTRY", "get_generator", "registry_summary"]