BimDown Agent Skill & Schema Rules

Your Mission: A bridge between AI agents and building data. Use this skill to read, understand, and create Building Information Models (BIM) exactly like reading and writing code. It enables you to execute architectural design, model from drawings, perform quantity surveying, and conduct model reviews. Of course, just modeling your own house is also very interesting and fully supported.

Setup / Prerequisites

Before executing any bimdown commands, ensure the CLI is installed globally.

SECURITY RULE: You MUST explicitly ask the user for permission before running npm install autonomously.

npm install -g bimdown-cli

You are an AI Coder operating within a BimDown project environment. BimDown is an open-source, AI-native building data format using CSV for semantics and SVG for geometry.

Core Architecture & Base Concepts

• Global Unit is METERS: All coordinates, widths, and structural attributes in CSV/SVG MUST strictly use METERS. BimDown simulates real-world dimensions.
• Computed Fields are READ-ONLY: Any field marked with computed: true (or listed in virtual_fields) is automatically calculated by the CLI. DO NOT write these fields to CSV files. You can retrieve their values using bimdown query.
• Dual Nature: Properties live in {name}.csv. 2D geometry lives in a sibling {name}.svg file. The id fields across both must match perfectly.
• SVG-derived virtual columns: When you write geometry in SVG, the CLI automatically computes these fields for bimdown query — do NOT write them to CSV:
  • Line elements (wall, beam, pipe, etc.): length, start_x, start_y, end_x, end_y
  • Polygon elements (slab, roof, etc.): area, perimeter
  • All elements: level_id (inferred from folder name, e.g. lv-1/ → lv-1)
• Concrete Example of CSV+SVG Linked State:

  lv-1/wall.csv (note: NO level_id column — it is auto-inferred): id,thickness,material w-1,0.2,concrete

  lv-1/wall.svg: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -10 10 10"> <g transform="scale(1,-1)"> <path id="w-1" d="M 0 0 L 10 0" stroke-width="0.2" /> </g> </svg>

  After this, bimdown query . "SELECT id, length, level_id FROM wall" returns w-1, 10.0, lv-1 — both length and level_id are computed automatically.

Project Directory Structure

project/
  project_metadata.json        # project root marker (format version, name, units)
  global/                      # global-only files — MUST be here, NOT in lv-N/
    grid.csv
    level.csv
    mesh.csv
  lv-1/                        # per-level files
    wall.csv + wall.svg        # elements with geometry have paired CSV+SVG
    door.csv                   # hosted elements are CSV-only (parametric position on host wall)
    space.csv                  # spaces: CSV seed point + space.svg boundary (computed by build)
    ...
  lv-2/
    ...

Key rules:

• level.csv, grid.csv, mesh.csv MUST live in global/, never in lv-N/ directories
• Per-level elements (wall, door, slab, space, etc.) go in lv-N/ directories
• The folder name (e.g. lv-1) becomes the element's level_id — do NOT write level_id to CSV

Recommended Workflow for Creating/Modifying Buildings

1. Plan spatial layout first: Before writing any files, reason through the spatial relationships — wall positions, room adjacencies, door/window placements. Sketch coordinates mentally or on paper.
2. Write SVG geometry first: Create the .svg files (walls, slabs, columns) with correct coordinates. Geometry determines everything else.
3. Write CSV attributes second: Create the .csv files with element properties (material, thickness, etc.). Remember: do NOT include computed fields like level_id, length, area.
4. Render and visually verify: Run bimdown render <dir> -o render.png and view the PNG image to confirm the layout is correct. Check that walls connect properly, rooms are enclosed, and doors/windows are in the right positions. Save render outputs and any other non-BimDown files OUTSIDE the project directory — the project directory must only contain BimDown CSV/SVG files, otherwise build will reject them.
5. Build: Run bimdown build <dir> to validate schema, check geometry, and compute space boundaries (generates space.svg from seed points).
6. Iterate: If the render or build shows problems, fix the SVG geometry and re-render until the layout looks right.
7. Publish: Run bimdown publish <dir> to upload and get a shareable 3D preview URL. Ask user for consent before the first publish of each project.

Reference SOPs

Before starting any building design or modeling task, always read the relevant reference SOP:

• Designing a building from scratch (from a user brief or requirements): Read references/building-design.md for the full design-to-BIM workflow — from massing through MEP.
• Modeling from existing plans (floor plan images, sketches, or known dimensions): Read references/bim-modeling.md for element creation order, dependencies, and best practices.

These are step-by-step standard operating procedures. Read the relevant one before writing any files.

CLI Tools & Best Practices

1. bimdown query <dir> <sql> --json: Runs DuckDB SQL across all tables, including SVG-derived virtual columns.
   • Example: bimdown query ./proj "SELECT id, length FROM wall WHERE length > 5.0" --json
2. bimdown render <dir> [-l level] [-o output.png] [-w width]: Renders a level into a PNG blueprint image (default 2048px wide). Use .svg extension for SVG output. Always render after modifying geometry and view the PNG to visually verify the result.
3. bimdown build <dir>: Validates the project, checks geometry (wall connectivity, hosted element bounds), and computes space boundaries (generates space.svg). Run this EVERY TIME after modifying CSV or SVG files! Also available as bimdown validate (alias).
4. bimdown schema [table]: Prints the full schema for any element type. Use this to look up fields before creating elements.
5. bimdown diff <dirA> <dirB>: Emits a +, -, ~ structural difference between project snapshots.
6. bimdown init <dir>: Creates a new empty BimDown project with the correct directory structure.
7. bimdown publish <dir> [--expires 7d]: Publishes the project to BimClaw and returns a shareable preview URL. Use this to let users view the model in a 3D editor. SECURITY WARNING: Uploads project data to an external server. You must ask for explicit user confirmation before running this command for the FIRST time on each project.
8. bimdown info <dir>: Prints project summary (levels, element counts).
9. bimdown resolve-topology <dir>: Auto-detects coincident endpoints for MEP curves, generates mep_nodes, and fills connectivity fields.
10. bimdown merge <dirs...> -o <output>: Merges multiple project directories into one, resolving ID conflicts.
11. bimdown sync <dir>: Hydrates into DuckDB and dehydrates back out to CSV/SVG, applying computed defaults.
12. Downloading a shared project: If the user provides a share link like https://bim-claw.com/s/<token>, append /download to get the zip: curl -L https://bim-claw.com/s/<token>/download -o project.zip && unzip project.zip -d project/

Critical File & Geometry Rules

• ID format:
  • Grid and Level allow any string after prefix: level: lv- + any string (e.g. lv-1, lv-A, lv-B2); grid: gr- + any string (e.g. gr-1, gr-A, gr-B2)
  • All other elements use {prefix}-{number} (digits only): wall → w-{n}, column → c-{n}, slab → sl-{n}, space → sp-{n}, door → d-{n}, window → wn-{n}, ...
  • Always run bimdown build to confirm your IDs are compliant.
• SVG Coordinate Y-Flip: All geometry inside .svg files MUST be wrapped in a Y-axis flip group: <g transform="scale(1,-1)"> ... </g>. This is just a fixed boilerplate — you do NOT need to do any coordinate conversion. Use normal Cartesian coordinates (X = right, Y = up) directly inside the group.
• CSV vs Computed Fields: Only write fields that are NOT marked as computed. Specifically, level_id, length, area, start_x/y, end_x/y, perimeter, volume, bbox_* are all auto-computed — never write them to CSV.
• Vertical positioning (walls, columns, and other vertical elements):
  • level_id: auto-inferred from folder name — do NOT write to CSV
  • base_offset: vertical offset in meters from the element's level. Default 0. Usually leave empty.
  • top_level_id: the level where the element's top is constrained. Leave empty to default to the next level above. Only set this if the element spans to a non-adjacent level.
  • top_offset: vertical offset in meters from the top level. Default 0. Usually leave empty.
  • height: auto-computed from level elevations and offsets — do NOT write to CSV.
  • For most single-story walls: leave top_level_id, top_offset, and base_offset all empty — the CLI will compute the correct height from level elevations.

Generation Tips

Typical Values (meters)

Room Boundary Connectivity

Rooms are enclosed by walls, curtain walls, columns, and room separators. For the boundary to close properly:

• Line element endpoints (walls, curtain walls, room separators) must meet exactly at shared coordinates
• Example: w-1 ends at (10,0) → w-2 must start at (10,0) for an L-junction
• The CLI build command warns about unconnected endpoints and computes space boundaries from closed loops

Door/Window Placement Rules

Recommended: use host_x, host_y instead of position. Just write the 2D coordinate of the opening center — bimdown build will auto-resolve the nearest wall and compute position for you.

id,host_x,host_y,width,height,operation,material
d-1,5.0,3.0,0.9,2.1,single,wood

After bimdown build, the CSV is rewritten with host_id and position replacing host_x/host_y. You can also provide host_id alongside host_x/host_y to force a specific wall.

Alternative: manual position = distance in meters from wall start point (the M coordinate in SVG path) to the opening center.

Validation rules (apply to both methods):

• Must satisfy: position - width/2 >= 0 AND position + width/2 <= wall_length
• Multiple openings on the same wall must not overlap
• The CLI build command warns about out-of-bounds and overlapping placements

SVG File Template

Always use this structure for SVG files:

<svg xmlns="http://www.w3.org/2000/svg">
  <g transform="scale(1,-1)">
    <!-- elements here, using normal Cartesian coordinates (X=right, Y=up) -->
  </g>
</svg>

Base Schema Reference

All elements inherit from element:

• Write to CSV: id (required), number, base_offset (default 0), mesh_file
• Query-only (computed, never write): level_id, created_at, updated_at, volume, bbox_min_x, bbox_min_y, bbox_min_z, bbox_max_x, bbox_max_y, bbox_max_z

Geometry bases — these fields are query-only (derived from SVG, never write to CSV):

• line_element (wall, beam, etc.): start_x, start_y, end_x, end_y, length
• point_element (column, equipment, etc.): x, y, rotation
• polygon_element (slab, roof, etc.): points, area, perimeter

Hosted elements (hosted_element): Use host_x/host_y (recommended) or host_id + position. See Door/Window Placement Rules above.

Vertical span (vertical_span): Write top_level_id, top_offset — see Vertical Positioning rules above. Query-only: height.

Material enum (materialized): concrete, steel, wood, clt, glass, aluminum, brick, stone, gypsum, insulation, copper, pvc, ceramic, fiber_cement, composite

Core Schema Topologies (Concrete Tables)

Below is a curated whitelist of the most commonly used core architectural elements.

IMPORTANT: The complete list of available elements in this project is: beam, brace, cable_tray, ceiling, column, conduit, curtain_wall, door, duct, equipment, foundation, grid, level, mep_node, mesh, opening, pipe, railing, ramp, roof, room_separator, slab, space, stair, structure_column, structure_slab, structure_wall, terminal, wall, window

If the user asks you to modify or generate elements not listed below, RUN bimdown schema <table_name> to fetch their requirements!

Table: door (Prefix: d)

• Geometry: CSV only. Use host_x, host_y or host_id + position to place on a wall.

id_prefix: d
name: door
bases:
  - hosted_element
  - materialized
host_type: wall

fields:
  - name: width
    type: float
    required: true

  - name: height
    type: float

  - name: operation
    type: enum
    values:
      - single_swing
      - double_swing
      - sliding
      - folding
      - revolving

  - name: hinge_position
    type: enum
    values:
      - start
      - end

  - name: swing_side
    type: enum
    values:
      - left
      - right

Table: grid (Prefix: gr)

• Geometry: CSV only

id_prefix: gr
name: grid

fields:
  - name: id
    type: string
    required: true

  - name: number
    type: string
    required: true

  - name: start_x
    type: float
    required: true

  - name: start_y
    type: float
    required: true

  - name: end_x
    type: float
    required: true

  - name: end_y
    type: float
    required: true

Table: level (Prefix: lv)

• Geometry: CSV only

id_prefix: lv
name: level

fields:
  - name: id
    type: string
    required: true

  - name: number
    type: string
    required: true

  - name: name
    type: string

  - name: elevation
    type: float
    required: true

Table: space (Prefix: sp)

• Geometry: SVG required

id_prefix: sp
name: space
bases:
  - element

fields:
  - name: x
    type: float
    required: true
    description: Seed point X coordinate (room interior point)

  - name: y
    type: float
    required: true
    description: Seed point Y coordinate (room interior point)

  - name: name
    type: string

  - name: boundary_points
    type: string
    computed: true
    description: Space boundary polygon vertices (computed by build from surrounding walls)

  - name: area
    type: float
    computed: true
    description: Space area in square meters (computed from boundary polygon)

Table: wall (Prefix: w)

• Geometry: SVG required
• IMPORTANT: A wall MUST be one complete straight line (start to end). Do NOT split a wall into segments for doors/windows. Doors and windows attach to the wall via the position parameter on the host wall.

id_prefix: w
name: wall
bases:
  - line_element
  - vertical_span
  - materialized

fields:
  - name: thickness
    type: float
    required: true
    description: Wall thickness in meters. SVG stroke-width should match but CSV is source of truth.

Table: window (Prefix: wn)

• Geometry: CSV only. Use host_x, host_y or host_id + position. Always set base_offset (sill height, typically 0.9m).

id_prefix: wn
name: window
bases:
  - hosted_element
  - materialized
host_type: wall

fields:
  - name: width
    type: float
    required: true

  - name: height
    type: float

Additional Resources

If you need more detailed information about the BimDown format, or if you need the conversion tool to round-trip data between Autodesk Revit and BimDown, please refer to the official GitHub repository: https://github.com/NovaShang/BimDown