KittyCAD · jacebrowning · Jun 25, 2026 · Jun 24, 2026
@@ -4,10 +4,18 @@ excerpt: "Known issues with the KCL standard library for the Zoo Design Studio."
 layout: manual
 ---
 
+## Geometry Engine
+
 The following are bugs that are not in Zoo Design Studio or KCL itself. These bugs,
 once fixed in engine, will just start working here with no language changes.
 
 - **Import**: Right now you can import a file, but even if that file has BREP data
     you cannot yet edit it, the engine will account for this later. 
 
 - **CSG Booleans**: Coplanar (bodies that share a plane) unions, subtractions, and intersections are not currently supported.
+
+## KCL Version 1.0
+
+The following are known issues with KCL 1.0. To opt-in to the fixes and new features, use the latest version of KCL with `@settings(kclVersion = 2.0)`.
+
+- **Region tags are shuffled**: When you name a segment in a sketch block, the tags in the region may not correspond to the original sketch segments. This is fixed in KCL 2.0.
@@ -27,7 +27,7 @@ For example:
 
 ```kcl
 // The settings attribute.
-@settings(defaultLengthUnit = in)
+@settings(kclVersion = 2.0, defaultLengthUnit = in)
 
 // The rest of your KCL code goes below...
 
@@ -45,5 +45,6 @@ Valid properties are:
 - `experimentalFeatures`: how experimental features are handled within this file.
   - Accepted values: `allow` (experimental features can be used freely), `warn` (experimental features
   cause a warning), `deny` (the default, experimental features cause an error).
+- `kclVersion`: the version of the KCL language and standard libary to execute with.
 
 These settings override any project-wide settings (configured in project.toml or via the UI).
@@ -7,6 +7,8 @@ layout: manual
 When you sketch on a plane and extrude, a new solid is created.
 
 ```kcl
+@settings(kclVersion = 2.0)
+
 squareSketch = sketch(on = XY) {
   line1 = line(start = [var 0mm, var 0mm], end = [var 1mm, var 0mm])
   line2 = line(start = [var 1mm, var 0mm], end = [var 1mm, var 1mm])
@@ -24,6 +26,8 @@ However, when you sketch on the face of an existing solid, extruding extends the
 existing solid.
 
 ```kcl
+@settings(kclVersion = 2.0)
+
 squareSketch = sketch(on = XY) {
   line1 = line(start = [var 0mm, var 0mm], end = [var 1mm, var 0mm])
   line2 = line(start = [var 1mm, var 0mm], end = [var 1mm, var 1mm])
@@ -36,7 +40,7 @@ squareSketch = sketch(on = XY) {
 region001 = region(segments = [squareSketch.line1, squareSketch.line2])
 cube = extrude(region001, length = 1)
 
-towerSketch = sketch(on = startSketchOn(cube, face = END)) {
+towerSketch = sketch(on = faceOf(cube, face = END)) {
   circle1 = circle(start = [var 0.6mm, var 0.5mm], center = [var 0.5mm, var 0.5mm])
 }
 region002 = region(segments = [towerSketch.circle1])
@@ -55,6 +59,8 @@ the sketch on the same plane. Since it's not directly on the first solid's face,
 extrusions do not modify the solid. They create new solids instead.
 
 ```kcl
+@settings(kclVersion = 2.0)
+
 squareSketch = sketch(on = XY) {
   line1 = line(start = [var 0mm, var 0mm], end = [var 1mm, var 0mm])
   line2 = line(start = [var 1mm, var 0mm], end = [var 1mm, var 1mm])
@@ -80,6 +86,8 @@ The second way to create a separate solid is by using the `method` parameter of
 that the method should create a new solid using `method = NEW`.
 
 ```kcl
+@settings(kclVersion = 2.0)
+
 squareSketch = sketch(on = XY) {
   line1 = line(start = [var 0mm, var 0mm], end = [var 1mm, var 0mm])
   line2 = line(start = [var 1mm, var 0mm], end = [var 1mm, var 1mm])
@@ -93,7 +101,7 @@ region001 = region(segments = [squareSketch.line1, squareSketch.line2])
 cube = extrude(region001, length = 1)
 
 // This tower is a separate solid from the cube.
-towerSketch = sketch(on = startSketchOn(cube, face = END)) {
+towerSketch = sketch(on = faceOf(cube, face = END)) {
   circle1 = circle(start = [var 0.6mm, var 0.5mm], center = [var 0.5mm, var 0.5mm])
 }
 region002 = region(segments = [towerSketch.circle1])

@@ -52,6 +52,8 @@ The syntax for declaring a tag is `$myTag`. Tags are used for bodies (such as ex
 **Example: Referencing sketch segments and tagging cap faces**
 
 ```kcl
+@settings(kclVersion = 2.0)
+
 sketch001 = sketch(on = XZ) {
   line1 = line(start = [var -2.17mm, var -0.91mm], end = [var 3.01mm, var -1.57mm])
   line2 = line(start = [var 3.01mm, var -1.57mm], end = [var 3.13mm, var 3.12mm])
@@ -68,7 +70,7 @@ fillet001 = fillet(extrude001, tags = getCommonEdge(faces = [region001.tags.line
 ```
 
 
-In this example, you reference sketch segments by their names (e.g., `line4`). Tags (using `$`) are only needed for cap faces or other body features.
+In this example, you reference sketch segments from sketch blocks by their names, using dot notation on the sketch (e.g. `sketch001.line4`). Sketches from KCL 1.0 (using `startSketchOn()`) and regions are scoped to tags, as in `region001.tags.line4`. Tags (using `$`) are only needed for cap faces or other body features.
 
 When a function requires declaring a new tag (using the `$` syntax), the argument has type [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl).
 
@@ -77,24 +79,32 @@ When a function requires declaring a new tag (using the `$` syntax), the argumen
 A tag created using a tag declarator can be used by writing its name without the `$`, e.g., `myTag`.
 Where necessary to disambiguate from tag declarations, we call these tag identifiers.
 
-In the example above we use the tag identifier `rectangleSegmentA001` to get the angle of the segment
-using `segAng(rectangleSegmentA001)`.
+In the example above we use the tag identifier `capEnd001` to get the edge in common
+using `getCommonEdge(capEnd001)`.
 
 
 Tags can identify an edge or face of a solid. Functions that take a tag identifier as an argument will use either [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) (for the edge of a solid) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace).
 
-For sketches, always use the segment name (e.g., `line1`, `line2`).
-
-#### `START` and `END`
+#### `START` and `END` vs. `body.faces`
 
 [`START`](/docs/kcl-std/consts/std-START) and [`END`](/docs/kcl-std/consts/std-END) are special tags
 for identifying the starting and ending faces of an extruded solid.
 
+Using `START` and `END` can be convenient sometimes, but they are generally discouraged since they're ambiguous. It's not clear what face is being referred to without also specifying the body.
+
+When you tag a face in an extrusion, it becomes one of that body's named faces. In the example above, `extrude001.faces.capEnd001` refers to the end-cap face.
+
+This is also useful when you create the body in a function and need to refer to one of its faces in the calling scope. You can simply return the body, and callers can access all of the body's named faces.
+
 
 ### Tag Scope
 
 Tags are scoped globally if declared in the root context. For bodies, you can use the tag anywhere in the file. For sketches, always use the segment name directly.
 
+For backward compatibility reasons, tags may leak outside of function scopes and be updated (i.e. re-bound to the face of a different body), which can be confusing about which geometry you're trying to refer to.
+
+For this reason, it's strongly preferred to use dot notation on the body, as in `extrude001.faces.capEnd001` for an end-cap face or `region001.tags.line4` for a wall face.
+
 ---
 
 If you find any issues using any of the above expressions or syntax,

@@ -1,6 +1,8 @@
 // GD&T Basics in Zoo Design Studio
 // A simple sample project demonstrating how to use GD&T in Zoo Design Studio. This project keeps the geometry and annotations intentionally minimal so users can quickly understand what GD&T is, how it works in the app, and how to start applying it to their own designs. Future updates may add more examples while keeping the project beginner-friendly.
 
+@settings(defaultLengthUnit = mm, kclVersion = 2.0)
+
 sketch001 = sketch(on = XY) {
   line1 = line(start = [var -99.36mm, var 49.61mm], end = [var 100.64mm, var 49.61mm])
   line2 = line(start = [var 100.64mm, var 49.61mm], end = [var 100.64mm, var -50.39mm])
@@ -25,6 +27,24 @@ extrude001 = extrude(
   tagEnd = $capEnd001,
   tagStart = $capStart001,
 )
+
+gdt::datum(
+  face = region001.tags.line2,
+  name = "A",
+  framePlane = XZ,
+  leaderScale = 1,
+)
+
+gdt::distance(
+  edges = [
+    getCommonEdge(faces = [region001.tags.line3, capEnd001])
+  ],
+  tolerance = 0.1mm,
+  framePosition = [0, 30],
+  framePlane = XZ,
+  fontSize = 9.3333mm,
+)
+
 gdt::flatness(
   faces = [region001.tags.line1],
   tolerance = 0.001mm,
@@ -33,12 +53,7 @@ gdt::flatness(
   leaderScale = 1,
   fontSize = 10mm,
 )
-gdt::datum(
-  face = region001.tags.line3,
-  name = "A",
-  framePlane = XZ,
-  leaderScale = 1,
-)
+
 gdt::perpendicularity(
   faces = [capEnd001],
   tolerance = 0.1mm,
@@ -47,28 +62,16 @@ gdt::perpendicularity(
   leaderScale = 1,
 )
 gdt::parallelism(
-  faces = [region001.tags.line2],
+  faces = [region001.tags.line4],
   tolerance = 0.2mm,
   datums = ["A"],
   framePlane = XZ,
   framePosition = [-100, 100],
   leaderScale = 1,
 )
-gdt::distance(
-  from = getCommonEdge(faces = [
-    region001.tags.line2,
-    region001.tags.line4
-  ]),
-  to = getCommonEdge(faces = [
-    region001.tags.line4,
-    region001.tags.line3
-  ]),
-  tolerance = 0.1mm,
-  framePlane = XZ,
-  leaderScale = 1,
-)
+
 gdt::annotation(
-  faces = [region001.tags.line4],
+  faces = [region001.tags.line3],
   annotation = "BREAK ALL SHARP EDGES",
   framePosition = [100, -100],
   leaderScale = 1,

@@ -11,7 +11,7 @@ GD&T angularity annotation specifying how much faces or edges may deviate from a
 gdt::angularity(
   tolerance: number(Length),
   faces?: [TaggedFace; 1+],
-  edges?: [Edge; 1+],
+  edges?: [Edge | any; 1+],
   datums?: [string; 1+],
   precision?: number(_),
   framePosition?: Point2d,
@@ -35,7 +35,7 @@ omitting both is an error.
 |----------|------|-------------|----------|
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The tolerance zone size for orientation at a basic angle. | Yes |
 | `faces` | [[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace); 1+] | The faces to be annotated. At least one of `faces` or `edges` must be supplied. | No |
-| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge); 1+] | The edges to be annotated. At least one of `faces` or `edges` must be supplied. | No |
+| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | The edges to be annotated. At least one of `faces` or `edges` must be supplied. Edge specifier objects (`{ sideFaces = [...], endFaces? = [...], index? = 0 }`) are experimental; do not use them in generated or user-facing KCL yet. | No |
 | `datums` | [[`string`](/docs/kcl-std/types/std-types-string); 1+] | The datum references to display in the feature control frame. Supports up to primary, secondary, and tertiary datums. | No |
 | `precision` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The number of decimal places to display. The default is `3`. Must be greater than or equal to `0` and less than or equal to `9`. | No |
 | `framePosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The position of the feature control frame relative to the leader arrow. The default is `[100mm, 100mm]`. | No |

@@ -11,7 +11,7 @@ GD&T annotation for attaching manufacturing text to faces or edges.
 gdt::annotation(
   annotation: string,
   faces?: [TaggedFace; 1+],
-  edges?: [Edge; 1+],
+  edges?: [Edge | any; 1+],
   framePosition?: Point2d,
   framePlane?: Plane,
   leaderScale?: number(_),
@@ -27,7 +27,7 @@ This is part of model-based definition (MBD).
 |----------|------|-------------|----------|
 | `annotation` | [`string`](/docs/kcl-std/types/std-types-string) | The annotation text to display. | Yes |
 | `faces` | [[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace); 1+] | The faces to be annotated. | No |
-| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge); 1+] | The edges to be annotated. | No |
+| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | The edges to be annotated. Edge specifier objects (`{ sideFaces = [...], endFaces? = [...], index? = 0 }`) are experimental; do not use them in generated or user-facing KCL yet. | No |
 | `framePosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The position of the annotation relative to the leader arrow. The default is `[100mm, 100mm]`. | No |
 | `framePlane` | [`Plane`](/docs/kcl-std/types/std-types-Plane) | The plane in which to display the annotation. The default is `XY`. Other standard planes like `XZ` and `YZ` can also be used. The annotation may be displayed in a plane parallel to the given plane. | No |
 | `leaderScale` | [`number(_)`](/docs/kcl-std/types/std-types-number) | Visual scale of the leader dot. The default is `1.0`, which maps to the calibrated normal dot size. The value is normalized against `fontSize` so the dot stays consistent as text size changes. Must be greater than `0`. | No |

@@ -11,7 +11,7 @@ GD&T annotation specifying how circular (round) a feature must be.
 gdt::circularity(
   tolerance: number(Length),
   faces?: [TaggedFace; 1+],
-  edges?: [Edge; 1+],
+  edges?: [Edge | any; 1+],
   precision?: number(_),
   framePosition?: Point2d,
   framePlane?: Plane,
@@ -37,7 +37,7 @@ Circularity is a form tolerance, so it does not reference datums.
 |----------|------|-------------|----------|
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The amount of deviation from a perfect circle that is acceptable. | Yes |
 | `faces` | [[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace); 1+] | The faces to be annotated. | No |
-| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge); 1+] | The edges to be annotated. | No |
+| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | The edges to be annotated. Edge specifier objects (`{ sideFaces = [...], endFaces? = [...], index? = 0 }`) are experimental; do not use them in generated or user-facing KCL yet. | No |
 | `precision` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The number of decimal places to display. The default is `3`. Must be greater than or equal to `0` and less than or equal to `9`. | No |
 | `framePosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The position of the feature control frame relative to the leader arrow. The default is `[100mm, 100mm]`. | No |
 | `framePlane` | [`Plane`](/docs/kcl-std/types/std-types-Plane) | The plane in which to display the feature control frame. The default is `XY`. Other standard planes like `XZ` and `YZ` can also be used. The frame may be displayed in a plane parallel to the given plane. | No |

@@ -12,7 +12,7 @@ gdt::concentricity(
   tolerance: number(Length),
   datums: [string; 1+],
   faces?: [TaggedFace; 1+],
-  edges?: [Edge; 1+],
+  edges?: [Edge | any; 1+],
   precision?: number(_),
   framePosition?: Point2d,
   framePlane?: Plane,
@@ -41,7 +41,7 @@ where appropriate. ISO standards use the name coaxiality for this concept.
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The diameter of the cylindrical tolerance zone. | Yes |
 | `datums` | [[`string`](/docs/kcl-std/types/std-types-string); 1+] | The datum references to display in the feature control frame. Supports up to primary, secondary, and tertiary datums. | Yes |
 | `faces` | [[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace); 1+] | The faces to be annotated. | No |
-| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge); 1+] | The edges to be annotated. | No |
+| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | The edges to be annotated. Edge specifier objects (`{ sideFaces = [...], endFaces? = [...], index? = 0 }`) are experimental; do not use them in generated or user-facing KCL yet. | No |
 | `precision` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The number of decimal places to display. The default is `3`. Must be greater than or equal to `0` and less than or equal to `9`. | No |
 | `framePosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The position of the feature control frame relative to the leader arrow. The default is `[100mm, 100mm]`. | No |
 | `framePlane` | [`Plane`](/docs/kcl-std/types/std-types-Plane) | The plane in which to display the feature control frame. The default is `XY`. Other standard planes like `XZ` and `YZ` can also be used. The frame may be displayed in a plane parallel to the given plane. | No |

@@ -11,7 +11,7 @@ GD&T annotation specifying how closely a feature must conform to a perfect cylin
 gdt::cylindricity(
   tolerance: number(Length),
   faces?: [TaggedFace; 1+],
-  edges?: [Edge; 1+],
+  edges?: [Edge | any; 1+],
   precision?: number(_),
   framePosition?: Point2d,
   framePlane?: Plane,
@@ -38,7 +38,7 @@ Cylindricity is a form tolerance, so it does not reference datums.
 |----------|------|-------------|----------|
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The amount of deviation from a perfect cylinder that is acceptable. | Yes |
 | `faces` | [[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace); 1+] | The faces to be annotated. | No |
-| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge); 1+] | The edges to be annotated. | No |
+| `edges` | [[`Edge`](/docs/kcl-std/types/std-types-Edge) or [`any`](/docs/kcl-std/types/std-types-any); 1+] | The edges to be annotated. Edge specifier objects (`{ sideFaces = [...], endFaces? = [...], index? = 0 }`) are experimental; do not use them in generated or user-facing KCL yet. | No |
 | `precision` | [`number(_)`](/docs/kcl-std/types/std-types-number) | The number of decimal places to display. The default is `3`. Must be greater than or equal to `0` and less than or equal to `9`. | No |
 | `framePosition` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The position of the feature control frame relative to the leader arrow. The default is `[100mm, 100mm]`. | No |
 | `framePlane` | [`Plane`](/docs/kcl-std/types/std-types-Plane) | The plane in which to display the feature control frame. The default is `XY`. Other standard planes like `XZ` and `YZ` can also be used. The frame may be displayed in a plane parallel to the given plane. | No |