Village Construction Set Library

This is the canonical part library for the Open Source Ecology Village Construction Set 12-foot modules, plus the validator toolkit that keeps entries checkable. The structure follows the OSE Schema Canon. Seeded design work is by Catarina and comes from the July 8, 2026 entry of Catarina Log.

Layout

library/
  parts/
  modules/
  assemblies/
  structures/
libtools/
tests/
upstream/catarina-2026-07-08/

The four library layers are:

• parts: Individual buildable pieces.
• modules: Reusable building modules.
• assemblies: Groups of modules and parts.
• structures: Whole structures. This layer is declared and currently empty.

Collections

Independent design families live below collections/ and use the same entry contract without becoming part of the housing library's default --root . discovery scope.

• GVCS machine library: sourced Universal Axis, Power Cube, and CEB Press geometry with preserved provenance and review status.

Read the repository docs:

• GOVERNANCE.md
• LIBRARY_ONTOLOGY.md
• CONTRIBUTING.md

Quickstart

git clone <repo-url>
cd vcs-library
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m libtools validate-code --root . --all

Compiling entries and validating output geometry requires freecadcmd:

.venv/bin/python -m libtools validate-output --root . --all

If freecadcmd is not on PATH, set FREECADCMD:

FREECADCMD=/path/to/freecadcmd .venv/bin/python -m libtools validate-output --root . --all

To compile browser-ready assets for selected entries, use bake-web. The output directory is required so the command never writes publishable files to an implicit location:

.venv/bin/python -m libtools bake-web --root . --output web-dist --all
.venv/bin/python -m libtools bake-web --root . --output web-dist \
  --asset-prefix assets/gvcs power_cube_ii

The command writes catalog.json, bake-report.json, and one deterministic mesh JSON plus normalized BREP per visible compiled solid. Relative --output paths are resolved below --root; --asset-prefix is a relative POSIX path inside the output directory and defaults to assets/gvcs. catalog.json is removed before compilation and written only after every selected entry bakes successfully, so a failed rebuild cannot leave a stale catalog.

Each entry is translated by its common bounding-box minimum, preserving all relative part placement while placing the entry at the browser origin. Meshes contain flat vertices and triangles arrays in millimeters and are tessellated from the compiled FreeCAD shapes at 0.5 mm deflection. Baking fails closed for null, invalid, open, non-solid, zero-volume, or empty-tessellation geometry. The catalog reports this check as validation.geometry; it reports the normal output validator and overlap check separately. Engineering review is always unreviewed, and overlap/completeness results do not block a web bake because authored assemblies can contain intentional overlaps. Catalog entries retain the source provenance mapping, license and license review, and geometry_mode; missing review or source fields remain empty or unspecified rather than being inferred from the local library version.

Current Contents

Layer	ID	Status	Title
part	sloped_rafter_flat_top_plate	wip	Single sloped roof rafter with corrected birdsmouth cuts
part	sloped_rafter_raked	active	Single sloped roof rafter with raked-wall birdsmouth cuts
module	ceiling_attic_storage	active	Ceiling with limited attic storage
module	extwall_front_rake	active	Exterior wall front rake module
module	extwall_side_rake	active	Exterior wall side rake module
module	extwall_single_door	active	Exterior wall single door module
module	extwall_standard	active	Standard exterior wall module
module	extwall_window	active	Exterior wall window module
assembly	cabin_walls_floor	active	Cabin floor and walls assembly
assembly	cabin_walls_floor_top_plate	active	Cabin floor, walls, and single top plate assembly
assembly	rake_wall_1	active	Rake wall assembly parametric base Z
assembly	rake_wall_2	active	Rake wall assembly with side rake modules

Validation Status

Code validation is enforced in CI on every push and pull request. Output geometry validation is enforced in CI for changes under library/, libtools/, pyproject.toml, and the output-validation workflow.