Tag types (#7458)

* Replace tag type with tagIdent and tagDecl

Signed-off-by: Nick Cameron <nrc@ncameron.org>

* Replace tagIdent with TaggedEdge and TaggedFace

Signed-off-by: Nick Cameron <nrc@ncameron.org>

---------

Signed-off-by: Nick Cameron <nrc@ncameron.org>

docs/kcl-lang/types.md

@@ -44,7 +44,7 @@ detail on importing geometry.
 
 Tags are used to give a name (tag) to a specific path.
 
-### `TagDeclarator`
+### Tag declarations - `TagDecl`
 
 The syntax for declaring a tag is `$myTag` you would use it in the following
 way:
@@ -67,24 +67,28 @@ startSketchOn(XZ)
   |> close()
 ```
 
-### `TagIdentifier`
+When a function requires declaring a new tag (using the `$` syntax), the argument has type [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl).
 
-As per the example above you can use the tag identifier to get a reference to the 
+### Tag identifiers
-tagged object. The syntax for this is `myTag`.
 
-In the example above we use the tag identifier to get the angle of the segment
+A tag created using a tag declarator can be used by writing its name without the `$`, e.g., `myTag`.
-`segAng(rectangleSegmentA001)`.
+Where necessary to disambiguate from tag declarations, we call these tag identifiers.
 
-### `Start`
+In the example above we use the tag identifier `rectangleSegmentA001` to get the angle of the segment
+using `segAng(rectangleSegmentA001)`.
 
-There is a special tag, `START` (with type `Start`, although under the cover, it's a string)
+Tags can identify either an edge or face of a solid, or a line or other edge of a sketch. Functions
-for identifying the face of a solid which was the start of an extrusion (i.e., the surface which
+which take a tag identifier as an argument will use either [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) (for the edge of a
-is extruded).
+solid or sketch) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace).
 
-### `End`
+If a line in a sketch is tagged and then the sketch is extruded, the tag is a `TaggedEdge` before
+extrusion and a `TaggedFace` after extrusion.
+
+#### `START` and `END`
+
+[`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.
 
-There is a special tag, `END` (with type `End`, although under the cover, it's a string)
-for identifying the face of a solid which was finishes an extrusion.
 
 ### Tag Scope
 

docs/kcl-std/consts/std-END.md

@@ -8,9 +8,13 @@ layout: manual
 Identifies the ending face of an extrusion. I.e., the new face created by an extrusion.
 
 ```kcl
-END: string = 'end'
+END: TaggedFace
 ```
 
 
 
+### Type
+
+[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) - A tag which references a face of a solid, including the distinguished tags `START` and `END`.
+
 

docs/kcl-std/consts/std-START.md

@@ -8,9 +8,13 @@ layout: manual
 Identifies the starting face of an extrusion. I.e., the face which is extruded.
 
 ```kcl
-START: string = 'start'
+START: TaggedFace
 ```
 
 
 
+### Type
+
+[`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) - A tag which references a face of a solid, including the distinguished tags `START` and `END`.
+
 

docs/kcl-std/consts/std-X.md

@@ -8,9 +8,13 @@ layout: manual
 The X-axis (can be used in both 2d and 3d contexts).
 
 ```kcl
-X
+X: Axis3d
 ```
 
 
 
+### Type
+
+[`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) - An abstract and infinite line in 3d space.
+
 

docs/kcl-std/consts/std-XY.md

@@ -8,9 +8,13 @@ layout: manual
 An abstract 3d plane aligned with the X and Y axes. Its normal is the positive Z axis.
 
 ```kcl
-XY
+XY: Plane
 ```
 
 
 
+### Type
+
+[`Plane`](/docs/kcl-std/types/std-types-Plane) - An abstract plane.
+
 

docs/kcl-std/consts/std-XZ.md

@@ -8,9 +8,13 @@ layout: manual
 An abstract 3d plane aligned with the X and Z axes. Its normal is the negative Y axis.
 
 ```kcl
-XZ
+XZ: Plane
 ```
 
 
 
+### Type
+
+[`Plane`](/docs/kcl-std/types/std-types-Plane) - An abstract plane.
+
 

docs/kcl-std/consts/std-Y.md

@@ -8,9 +8,13 @@ layout: manual
 The Y-axis (can be used in both 2d and 3d contexts).
 
 ```kcl
-Y
+Y: Axis3d
 ```
 
 
 
+### Type
+
+[`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) - An abstract and infinite line in 3d space.
+
 

docs/kcl-std/consts/std-YZ.md

@@ -8,9 +8,13 @@ layout: manual
 An abstract 3d plane aligned with the Y and Z axes. Its normal is the positive X axis.
 
 ```kcl
-YZ
+YZ: Plane
 ```
 
 
 
+### Type
+
+[`Plane`](/docs/kcl-std/types/std-types-Plane) - An abstract plane.
+
 

docs/kcl-std/consts/std-Z.md

@@ -8,9 +8,13 @@ layout: manual
 The 3D Z-axis.
 
 ```kcl
-Z
+Z: Axis3d
 ```
 
 
 
+### Type
+
+[`Axis3d`](/docs/kcl-std/types/std-types-Axis3d) - An abstract and infinite line in 3d space.
+
 

docs/kcl-std/consts/std-math-E.md

@@ -13,6 +13,10 @@ E: number = 2.71828182845904523536028747135266250_
 
 
 
+### Type
+
+[`number`](/docs/kcl-std/types/std-types-number) - A number.
+
 ### Examples
 
 ```kcl

docs/kcl-std/consts/std-math-PI.md

@@ -11,7 +11,7 @@ The value of `pi`, Archimedes’ constant (π).
 PI: number(_?) = 3.14159265358979323846264338327950288_?
 ```
 
-`PI` is a number and is technically a ratio, so you might expect it to have type `number(_)`.
+`PI` is a number and is technically a ratio, so you might expect it to have type [`number(_)`](/docs/kcl-std/types/std-types-number).
 However, `PI` is nearly always used for converting between different units - usually degrees to or
 from radians. Therefore, `PI` is treated a bit specially by KCL and always has unknown units. This
 means that if you use `PI`, you will need to give KCL some extra information about the units of numbers.
@@ -19,6 +19,10 @@ Usually you should use type ascription on the result of calculations, e.g., `(2
 It is better to use `units::toRadians` or `units::toDegrees` to convert between angles with
 different units where possible.
 
+### Type
+
+[`number(_?)`](/docs/kcl-std/types/std-types-number) - A number.
+
 ### Examples
 
 ```kcl

docs/kcl-std/consts/std-math-TAU.md

@@ -13,6 +13,10 @@ TAU: number = 6.28318530717958647692528676655900577_
 
 
 
+### Type
+
+[`number`](/docs/kcl-std/types/std-types-number) - A number.
+
 ### Examples
 
 ```kcl

docs/kcl-std/consts/std-sweep-SKETCH_PLANE.md

@@ -13,4 +13,8 @@ sweep::SKETCH_PLANE: string = 'sketchPlane'
 
 
 
+### Type
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
 

docs/kcl-std/consts/std-sweep-TRAJECTORY.md

@@ -13,4 +13,8 @@ sweep::TRAJECTORY: string = 'trajectoryCurve'
 
 
 
+### Type
+
+[`string`](/docs/kcl-std/types/std-types-string) - A sequence of characters
+
 

docs/kcl-std/consts/std-turns-HALF_TURN.md

@@ -13,4 +13,8 @@ turns::HALF_TURN: number(deg) = 180deg
 
 
 
+### Type
+
+[`number(deg)`](/docs/kcl-std/types/std-types-number) - A number.
+
 

docs/kcl-std/consts/std-turns-QUARTER_TURN.md

@@ -13,4 +13,8 @@ turns::QUARTER_TURN: number(deg) = 90deg
 
 
 
+### Type
+
+[`number(deg)`](/docs/kcl-std/types/std-types-number) - A number.
+
 

docs/kcl-std/consts/std-turns-THREE_QUARTER_TURN.md

@@ -13,4 +13,8 @@ turns::THREE_QUARTER_TURN: number(deg) = 270deg
 
 
 
+### Type
+
+[`number(deg)`](/docs/kcl-std/types/std-types-number) - A number.
+
 

docs/kcl-std/consts/std-turns-ZERO.md

@@ -8,9 +8,13 @@ layout: manual
 No turn, zero degrees/radians.
 
 ```kcl
-turns::ZERO
+turns::ZERO: number(Angle)
 ```
 
 
 
+### Type
+
+[`number(Angle)`](/docs/kcl-std/types/std-types-number) - A number.
+
 

docs/kcl-std/functions/std-sketch-angledLine.md

@@ -16,7 +16,7 @@ angledLine(
   lengthY?: number(Length),
   endAbsoluteX?: number(Length),
   endAbsoluteY?: number(Length),
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -33,7 +33,7 @@ angledLine(
 | `lengthY` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Draw the line this distance along the Y axis. Only one of `length`, `lengthX`, `lengthY`, `endAbsoluteX`, `endAbsoluteY` can be given. | No |
 | `endAbsoluteX` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Draw the line along the given angle until it reaches this point along the X axis. Only one of `length`, `lengthX`, `lengthY`, `endAbsoluteX`, `endAbsoluteY` can be given. | No |
 | `endAbsoluteY` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Draw the line along the given angle until it reaches this point along the Y axis. Only one of `length`, `lengthX`, `lengthY`, `endAbsoluteX`, `endAbsoluteY` can be given. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-angledLineThatIntersects.md

@@ -11,9 +11,9 @@ Draw an angled line from the current origin, constructing a line segment such th
 angledLineThatIntersects(
   @sketch: Sketch,
   angle: number(Angle),
-  intersectTag: tag,
+  intersectTag: TaggedEdge,
   offset?: number(Length),
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -25,9 +25,9 @@ angledLineThatIntersects(
 |----------|------|-------------|----------|
 | `sketch` | [`Sketch`](/docs/kcl-std/types/std-types-Sketch) | Which sketch should this path be added to? | Yes |
 | `angle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | Which angle should the line be drawn at? | Yes |
-| `intersectTag` | [`tag`](/docs/kcl-std/types/std-types-tag) | The tag of the line to intersect with. | Yes |
+| `intersectTag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The tag of the line to intersect with. | Yes |
 | `offset` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The offset from the intersecting line. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-arc.md

@@ -16,7 +16,7 @@ arc(
   diameter?: number(Length),
   interiorAbsolute?: Point2d,
   endAbsolute?: Point2d,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -40,7 +40,7 @@ for to construct your shape, you're likely looking for tangentialArc.
 | `diameter` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How large should the circle be? Incompatible with `radius`. | No |
 | `interiorAbsolute` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Any point between the arc's start and end? Requires `endAbsolute`. Incompatible with `angleStart` or `angleEnd`. | No |
 | `endAbsolute` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Where should this arc end? Requires `interiorAbsolute`. Incompatible with `angleStart` or `angleEnd`. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this arc. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this arc. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-bezierCurve.md

@@ -16,7 +16,7 @@ bezierCurve(
   control1Absolute?: Point2d,
   control2Absolute?: Point2d,
   endAbsolute?: Point2d,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -33,7 +33,7 @@ bezierCurve(
 | `control1Absolute` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | First control point for the cubic. Absolute point. | No |
 | `control2Absolute` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Second control point for the cubic. Absolute point. | No |
 | `endAbsolute` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Coordinate on the plane at which this line should end. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-circle.md

@@ -13,7 +13,7 @@ circle(
   center: Point2d,
   radius?: number(Length),
   diameter?: number(Length),
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -27,7 +27,7 @@ circle(
 | `center` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The center of the circle. | Yes |
 | `radius` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The radius of the circle. Incompatible with `diameter`. | No |
 | `diameter` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The diameter of the circle. Incompatible with `radius`. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this circle. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this circle. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-circleThreePoint.md

@@ -13,7 +13,7 @@ circleThreePoint(
   p1: Point2d,
   p2: Point2d,
   p3: Point2d,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -27,7 +27,7 @@ circleThreePoint(
 | `p1` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | 1st point to derive the circle. | Yes |
 | `p2` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | 2nd point to derive the circle. | Yes |
 | `p3` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | 3rd point to derive the circle. | Yes |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Identifier for the circle to reference elsewhere. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Identifier for the circle to reference elsewhere. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-close.md

@@ -10,7 +10,7 @@ Construct a line segment from the current origin back to the profile's origin, e
 ```kcl
 close(
   @sketch: Sketch,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -24,7 +24,7 @@ starting point.
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `sketch` | [`Sketch`](/docs/kcl-std/types/std-types-Sketch) | The sketch you want to close. | Yes |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-extrude.md

@@ -13,8 +13,8 @@ extrude(
   length: number(Length),
   symmetric?: bool,
   bidirectionalLength?: number(Length),
-  tagStart?: tag,
+  tagStart?: TagDecl,
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+]
 ```
 
@@ -29,8 +29,8 @@ extruded in the same direction.
 | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How far to extrude the given sketches. | Yes |
 | `symmetric` | [`bool`](/docs/kcl-std/types/std-types-bool) | If true, the extrusion will happen symmetrically around the sketch. Otherwise, the extrusion will happen on only one side of the sketch. | No |
 | `bidirectionalLength` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | If specified, will also extrude in the opposite direction to 'distance' to the specified distance. If 'symmetric' is true, this value is ignored. | No |
-| `tagStart` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the start of the extrusion, i.e. the original sketch. | No |
+| `tagStart` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the start of the extrusion, i.e. the original sketch. | No |
-| `tagEnd` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch. | No |
+| `tagEnd` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-extrudeTwist.md

@@ -30,8 +30,8 @@ extruded in the same direction with the same twist.
 | `angle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | The total angle that the sketch will be twisted around | Yes |
 | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How far to extrude the given sketches. | Yes |
 | `angleStep` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | The size of each intermediate angle as the sketch twists around. Must be between 4 and 90 degrees. Defaults to 15 degrees. | No |
-| `tagStart` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the start of the extrusion, i.e. the original sketch. | No |
+| `tagStart` | `tag` | A named tag for the face at the start of the extrusion, i.e. the original sketch. | No |
-| `tagEnd` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch. | No |
+| `tagEnd` | `tag` | A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch. | No |
 | `center` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | The center around which the sketch will be twisted. Relative to the sketch's center. If not given, defaults to 0,0 i.e. the sketch's center. | No |
 
 ### Returns

docs/kcl-std/functions/std-sketch-getCommonEdge.md

@@ -8,7 +8,7 @@ layout: manual
 Get the shared edge between two faces.
 
 ```kcl
-getCommonEdge(faces: [tag; 2]): Edge
+getCommonEdge(faces: [TaggedFace; 2]): Edge
 ```
 
 
@@ -17,7 +17,7 @@ getCommonEdge(faces: [tag; 2]): Edge
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `faces` | `[tag; 2]` | The tags of the faces you want to find the common edge between. | Yes |
+| `faces` | `[TaggedFace; 2]` | The tags of the faces you want to find the common edge between. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-getNextAdjacentEdge.md

@@ -8,7 +8,7 @@ layout: manual
 Get the next adjacent edge to the edge given.
 
 ```kcl
-getNextAdjacentEdge(@edge: tag): Edge
+getNextAdjacentEdge(@edge: TaggedEdge): Edge
 ```
 
 
@@ -17,7 +17,7 @@ getNextAdjacentEdge(@edge: tag): Edge
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `edge` | [`tag`](/docs/kcl-std/types/std-types-tag) | The tag of the edge you want to find the next adjacent edge of. | Yes |
+| `edge` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The tag of the edge you want to find the next adjacent edge of. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-getOppositeEdge.md

@@ -8,7 +8,7 @@ layout: manual
 Get the opposite edge to the edge given.
 
 ```kcl
-getOppositeEdge(@edge: tag): Edge
+getOppositeEdge(@edge: TaggedEdge): Edge
 ```
 
 
@@ -17,7 +17,7 @@ getOppositeEdge(@edge: tag): Edge
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `edge` | [`tag`](/docs/kcl-std/types/std-types-tag) | The tag of the edge you want to find the opposite edge of. | Yes |
+| `edge` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The tag of the edge you want to find the opposite edge of. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-getPreviousAdjacentEdge.md

@@ -8,7 +8,7 @@ layout: manual
 Get the previous adjacent edge to the edge given.
 
 ```kcl
-getPreviousAdjacentEdge(@edge: tag): Edge
+getPreviousAdjacentEdge(@edge: TaggedEdge): Edge
 ```
 
 
@@ -17,7 +17,7 @@ getPreviousAdjacentEdge(@edge: tag): Edge
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `edge` | [`tag`](/docs/kcl-std/types/std-types-tag) | The tag of the edge you want to find the previous adjacent edge of. | Yes |
+| `edge` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The tag of the edge you want to find the previous adjacent edge of. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-involuteCircular.md

@@ -14,7 +14,7 @@ involuteCircular(
   endRadius: number(Length),
   angle: number(Angle),
   reverse?: bool,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -29,7 +29,7 @@ involuteCircular(
 | `endRadius` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The involute is described between two circles, end_radius is the radius of the outer circle. | Yes |
 | `angle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | The angle to rotate the involute by. A value of zero will produce a curve with a tangent along the x-axis at the start point of the curve. | Yes |
 | `reverse` | [`bool`](/docs/kcl-std/types/std-types-bool) | If reverse is true, the segment will start from the end of the involute, otherwise it will start from that start. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-line.md

@@ -12,7 +12,7 @@ line(
   @sketch: Sketch,
   endAbsolute?: Point2d,
   end?: Point2d,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -25,7 +25,7 @@ line(
 | `sketch` | [`Sketch`](/docs/kcl-std/types/std-types-Sketch) | Which sketch should this path be added to? | Yes |
 | `endAbsolute` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Which absolute point should this line go to? Incompatible with `end`. | No |
 | `end` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | How far away (along the X and Y axes) should this line go? Incompatible with `endAbsolute`. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-loft.md

@@ -14,8 +14,8 @@ loft(
   bezApproximateRational?: bool,
   baseCurveIndex?: number(_),
   tolerance?: number(Length),
-  tagStart?: tag,
+  tagStart?: TagDecl,
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): Solid
 ```
 
@@ -30,8 +30,8 @@ The sketches need to be closed and on different planes that are parallel.
 | `bezApproximateRational` | [`bool`](/docs/kcl-std/types/std-types-bool) | Attempt to approximate rational curves (such as arcs) using a bezier. This will remove banding around interpolations between arcs and non-arcs. It may produce errors in other scenarios. Over time, this field won't be necessary. | No |
 | `baseCurveIndex` | [`number(_)`](/docs/kcl-std/types/std-types-number) | This can be set to override the automatically determined topological base curve, which is usually the first section encountered. | No |
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Tolerance for the loft operation. | No |
-| `tagStart` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the start of the loft, i.e. the original sketch. | No |
+| `tagStart` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the start of the loft, i.e. the original sketch. | No |
-| `tagEnd` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the end of the loft. | No |
+| `tagEnd` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the end of the loft. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-revolve.md

@@ -15,8 +15,8 @@ revolve(
   tolerance?: number(Length),
   symmetric?: bool,
   bidirectionalAngle?: number(Angle),
-  tagStart?: tag,
+  tagStart?: TagDecl,
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+]
 ```
 
@@ -41,8 +41,8 @@ revolved around the same axis.
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Tolerance for the revolve operation. | No |
 | `symmetric` | [`bool`](/docs/kcl-std/types/std-types-bool) | If true, the extrusion will happen symmetrically around the sketch. Otherwise, the extrusion will happen on only one side of the sketch. | No |
 | `bidirectionalAngle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | If specified, will also revolve in the opposite direction to 'angle' to the specified angle. If 'symmetric' is true, this value is ignored. | No |
-| `tagStart` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the start of the revolve, i.e. the original sketch. | No |
+| `tagStart` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the start of the revolve, i.e. the original sketch. | No |
-| `tagEnd` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the end of the revolve. | No |
+| `tagEnd` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the end of the revolve. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segAng.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the angle (in degrees) of the provided line segment.
 
 ```kcl
-segAng(@tag: tag): number(Angle)
+segAng(@tag: TaggedEdge): number(Angle)
 ```
 
 
@@ -17,7 +17,7 @@ segAng(@tag: tag): number(Angle)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segEnd.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the ending point of the provided line segment.
 
 ```kcl
-segEnd(@tag: tag): Point2d
+segEnd(@tag: TaggedEdge): Point2d
 ```
 
 
@@ -17,7 +17,7 @@ segEnd(@tag: tag): Point2d
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segEndX.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the ending point of the provided line segment along the 'x' axis.
 
 ```kcl
-segEndX(@tag: tag): number(Length)
+segEndX(@tag: TaggedEdge): number(Length)
 ```
 
 
@@ -17,7 +17,7 @@ segEndX(@tag: tag): number(Length)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segEndY.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the ending point of the provided line segment along the 'y' axis.
 
 ```kcl
-segEndY(@tag: tag): number(Length)
+segEndY(@tag: TaggedEdge): number(Length)
 ```
 
 
@@ -17,7 +17,7 @@ segEndY(@tag: tag): number(Length)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segLen.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the length of the provided line segment.
 
 ```kcl
-segLen(@tag: tag): number(Length)
+segLen(@tag: TaggedEdge): number(Length)
 ```
 
 
@@ -17,7 +17,7 @@ segLen(@tag: tag): number(Length)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segStart.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the starting point of the provided line segment.
 
 ```kcl
-segStart(@tag: tag): Point2d
+segStart(@tag: TaggedEdge): Point2d
 ```
 
 
@@ -17,7 +17,7 @@ segStart(@tag: tag): Point2d
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segStartX.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the starting point of the provided line segment along the 'x' axis.
 
 ```kcl
-segStartX(@tag: tag): number(Length)
+segStartX(@tag: TaggedEdge): number(Length)
 ```
 
 
@@ -17,7 +17,7 @@ segStartX(@tag: tag): number(Length)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-segStartY.md

@@ -8,7 +8,7 @@ layout: manual
 Compute the starting point of the provided line segment along the 'y' axis.
 
 ```kcl
-segStartY(@tag: tag): number(Length)
+segStartY(@tag: TaggedEdge): number(Length)
 ```
 
 
@@ -17,7 +17,7 @@ segStartY(@tag: tag): number(Length)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-startProfile.md

@@ -11,7 +11,7 @@ Start a new profile at a given point.
 startProfile(
   @startProfileOn: Plane | Face,
   at: Point2d,
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -23,7 +23,7 @@ startProfile(
 |----------|------|-------------|----------|
 | `startProfileOn` | [`Plane`](/docs/kcl-std/types/std-types-Plane) or [`Face`](/docs/kcl-std/types/std-types-Face) | What to start the profile on. | Yes |
 | `at` | [`Point2d`](/docs/kcl-std/types/std-types-Point2d) | Where to start the profile. An absolute point. | Yes |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Tag this first starting point. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Tag this first starting point. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-startSketchOn.md

@@ -10,7 +10,7 @@ Start a new 2-dimensional sketch on a specific plane or face.
 ```kcl
 startSketchOn(
   @planeOrSolid: Solid | Plane,
-  face?: tag,
+  face?: TaggedFace,
 ): Plane | Face
 ```
 
@@ -36,7 +36,7 @@ face, since it will include all the parent faces and Solids.
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
 | `planeOrSolid` | [`Solid`](/docs/kcl-std/types/std-types-Solid) or [`Plane`](/docs/kcl-std/types/std-types-Plane) | Profile whose start is being used. | Yes |
-| `face` | [`tag`](/docs/kcl-std/types/std-types-tag) | Identify a face of a solid if a solid is specified as the input argument (`planeOrSolid`). | No |
+| `face` | [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) | Identify a face of a solid if a solid is specified as the input argument (`planeOrSolid`). | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-sweep.md

@@ -14,8 +14,8 @@ sweep(
   sectional?: bool,
   tolerance?: number(Length),
   relativeTo?: string,
-  tagStart?: tag,
+  tagStart?: TagDecl,
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+]
 ```
 
@@ -37,8 +37,8 @@ swept along the same path.
 | `sectional` | [`bool`](/docs/kcl-std/types/std-types-bool) | If true, the sweep will be broken up into sub-sweeps (extrusions, revolves, sweeps) based on the trajectory path components. | No |
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Tolerance for this operation. | No |
 | `relativeTo` | [`string`](/docs/kcl-std/types/std-types-string) | What is the sweep relative to? Can be either 'sketchPlane' or 'trajectoryCurve'. | No |
-| `tagStart` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the start of the sweep, i.e. the original sketch. | No |
+| `tagStart` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the start of the sweep, i.e. the original sketch. | No |
-| `tagEnd` | [`tag`](/docs/kcl-std/types/std-types-tag) | A named tag for the face at the end of the sweep. | No |
+| `tagEnd` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | A named tag for the face at the end of the sweep. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-tangentToEnd.md

@@ -8,7 +8,7 @@ layout: manual
 Returns the angle coming out of the end of the segment in degrees.
 
 ```kcl
-tangentToEnd(@tag: tag): number(Angle)
+tangentToEnd(@tag: TaggedEdge): number(Angle)
 ```
 
 
@@ -17,7 +17,7 @@ tangentToEnd(@tag: tag): number(Angle)
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | The line segment being queried by its tag. | Yes |
+| `tag` | [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) | The line segment being queried by its tag. | Yes |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-tangentialArc.md

@@ -15,7 +15,7 @@ tangentialArc(
   radius?: number(Length),
   diameter?: number(Length),
   angle?: number(Angle),
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -35,7 +35,7 @@ for 'angle' degrees along the imaginary circle.
 | `radius` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Radius of the imaginary circle. `angle` must be given. Incompatible with `end` and `endAbsolute` and `diameter`. | No |
 | `diameter` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Diameter of the imaginary circle. `angle` must be given. Incompatible with `end` and `endAbsolute` and `radius`. | No |
 | `angle` | [`number(Angle)`](/docs/kcl-std/types/std-types-number) | Offset of the arc. `radius` must be given. Incompatible with `end` and `endAbsolute`. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this arc. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this arc. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-xLine.md

@@ -12,7 +12,7 @@ xLine(
   @sketch: Sketch,
   length?: number(Length),
   endAbsolute?: number(Length),
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -25,7 +25,7 @@ xLine(
 | `sketch` | [`Sketch`](/docs/kcl-std/types/std-types-Sketch) | Which sketch should this path be added to? | Yes |
 | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How far away along the X axis should this line go? Incompatible with `endAbsolute`. | No |
 | `endAbsolute` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Which absolute X value should this line go to? Incompatible with `length`. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-sketch-yLine.md

@@ -12,7 +12,7 @@ yLine(
   @sketch: Sketch,
   length?: number(Length),
   endAbsolute?: number(Length),
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch
 ```
 
@@ -25,7 +25,7 @@ yLine(
 | `sketch` | [`Sketch`](/docs/kcl-std/types/std-types-Sketch) | Which sketch should this path be added to? | Yes |
 | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | How far away along the Y axis should this line go? Incompatible with `endAbsolute`. | No |
 | `endAbsolute` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | Which absolute Y value should this line go to? Incompatible with `length`. | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this line. | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this line. | No |
 
 ### Returns
 

docs/kcl-std/functions/std-solid-chamfer.md

@@ -12,7 +12,7 @@ chamfer(
   @solid: Solid,
   length: number(Length),
   tags: [Edge; 1+],
-  tag?: tag,
+  tag?: TagDecl,
 ): Solid
 ```
 
@@ -27,7 +27,7 @@ a sharp, straight transitional edge.
 | `solid` | [`Solid`](/docs/kcl-std/types/std-types-Solid) | The solid whose edges should be chamfered | Yes |
 | `length` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The length of the chamfer | Yes |
 | `tags` | [`[Edge; 1+]`](/docs/kcl-std/types/std-types-Edge) | The paths you want to chamfer | Yes |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this chamfer | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this chamfer | No |
 
 ### Returns
 

docs/kcl-std/functions/std-solid-fillet.md

@@ -13,7 +13,7 @@ fillet(
   radius: number(Length),
   tags: [Edge; 1+],
   tolerance?: number(Length),
-  tag?: tag,
+  tag?: TagDecl,
 ): Solid
 ```
 
@@ -29,7 +29,7 @@ will smoothly blend the transition.
 | `radius` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The radius of the fillet | Yes |
 | `tags` | [`[Edge; 1+]`](/docs/kcl-std/types/std-types-Edge) | The paths you want to fillet | Yes |
 | `tolerance` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The tolerance for this fillet | No |
-| [`tag`](/docs/kcl-std/types/std-types-tag) | [`tag`](/docs/kcl-std/types/std-types-tag) | Create a new tag which refers to this fillet | No |
+| `tag` | [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl) | Create a new tag which refers to this fillet | No |
 
 ### Returns
 

docs/kcl-std/functions/std-solid-shell.md

@@ -11,7 +11,7 @@ Remove volume from a 3-dimensional shape such that a wall of the provided thickn
 shell(
   @solids: [Solid; 1+],
   thickness: number(Length),
-  faces: [tag; 1+],
+  faces: [TaggedFace; 1+],
 ): [Solid]
 ```
 
@@ -23,7 +23,7 @@ shell(
 |----------|------|-------------|----------|
 | `solids` | [`[Solid; 1+]`](/docs/kcl-std/types/std-types-Solid) | Which solid (or solids) to shell out | Yes |
 | `thickness` | [`number(Length)`](/docs/kcl-std/types/std-types-number) | The thickness of the shell | Yes |
-| `faces` | [`[tag; 1+]`](/docs/kcl-std/types/std-types-tag) | The faces you want removed | Yes |
+| `faces` | [`[TaggedFace; 1+]`](/docs/kcl-std/types/std-types-TaggedFace) | The faces you want removed | Yes |
 
 ### Returns
 

docs/kcl-std/index.md

@@ -146,12 +146,12 @@ See also the [types overview](/docs/kcl-lang/types)
 
 * [**Primitive types**](/docs/kcl-lang/types)
   * [`ImportedGeometry`](/docs/kcl-std/types/std-types-ImportedGeometry)
+  * [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl)
   * [`any`](/docs/kcl-std/types/std-types-any)
   * [`bool`](/docs/kcl-std/types/std-types-bool)
   * [`fn`](/docs/kcl-std/types/std-types-fn)
   * [`number`](/docs/kcl-std/types/std-types-number)
   * [`string`](/docs/kcl-std/types/std-types-string)
-  * [`tag`](/docs/kcl-std/types/std-types-tag)
 * [**std::types**](/docs/kcl-std/modules/std-types)
   * [`Axis2d`](/docs/kcl-std/types/std-types-Axis2d)
   * [`Axis3d`](/docs/kcl-std/types/std-types-Axis3d)
@@ -163,3 +163,5 @@ See also the [types overview](/docs/kcl-lang/types)
   * [`Point3d`](/docs/kcl-std/types/std-types-Point3d)
   * [`Sketch`](/docs/kcl-std/types/std-types-Sketch)
   * [`Solid`](/docs/kcl-std/types/std-types-Solid)
+  * [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge)
+  * [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace)

docs/kcl-std/modules/std-types.md

@@ -24,6 +24,9 @@ Types can (optionally) be used to describe a function's arguments and returned v
 * [`Point3d`](/docs/kcl-std/types/std-types-Point3d)
 * [`Sketch`](/docs/kcl-std/types/std-types-Sketch)
 * [`Solid`](/docs/kcl-std/types/std-types-Solid)
+* [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl)
+* [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge)
+* [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace)
 * [`any`](/docs/kcl-std/types/std-types-any)
 * [`bool`](/docs/kcl-std/types/std-types-bool)
 * [`fn`](/docs/kcl-std/types/std-types-fn)

docs/kcl-std/types/std-types-TagDecl.md

@@ -0,0 +1,102 @@
+---
+title: "TagDecl"
+subtitle: "Type in std::types"
+excerpt: "Tags are used to give a name (tag) to a specific path."
+layout: manual
+---
+
+Tags are used to give a name (tag) to a specific path.
+
+### Tag Declaration
+
+The syntax for declaring a tag is `$myTag`. You would use it in the following
+way:
+
+```js
+startSketchOn(XZ)
+  |> startProfile(at = origin)
+  |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
+  |> angledLine(
+       angle = segAng(rectangleSegmentA001) - 90deg,
+       length = 196.99,
+       tag = $rectangleSegmentB001,
+     )
+  |> angledLine(
+       angle = segAng(rectangleSegmentA001),
+       length = -segLen(rectangleSegmentA001),
+       tag = $rectangleSegmentC001,
+     )
+  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
+  |> close()
+```
+
+### Tag Scope
+
+Tags are scoped globally if in the root context meaning in this example you can
+use the tag `rectangleSegmentA001` in any function or expression in the file.
+
+However if the code was written like this:
+
+```js
+fn rect(origin) {
+  return startSketchOn(XZ)
+    |> startProfile(at = origin)
+    |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
+    |> angledLine(
+         angle = segAng(rectangleSegmentA001) - 90,
+         length = 196.99,
+         tag = $rectangleSegmentB001
+       )
+    |> angledLine(
+         angle = segAng(rectangleSegmentA001),
+         length = -segLen(rectangleSegmentA001),
+         tag = $rectangleSegmentC001
+       )
+    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
+    |> close()
+}
+
+rect(origin = [0, 0])
+rect(origin = [20, 0])
+```
+
+Those tags would only be available in the `rect` function and not globally.
+
+However you likely want to use those tags somewhere outside the `rect` function.
+
+Tags are accessible through the sketch group they are declared in.
+For example the following code works.
+
+```js
+fn rect(origin) {
+  return startSketchOn(XZ)
+    |> startProfile(at = origin)
+    |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
+    |> angledLine(
+         angle = segAng(rectangleSegmentA001) - 90deg,
+         length = 196.99,
+         tag = $rectangleSegmentB001,
+       )
+    |> angledLine(
+         angle = segAng(rectangleSegmentA001),
+         length = -segLen(rectangleSegmentA001),
+         tag = $rectangleSegmentC001,
+       )
+    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
+    |> close()
+}
+
+rect(origin = [0, 0])
+myRect = rect(origin = [20, 0])
+
+myRect
+  |> extrude(length = 10)
+  |> fillet(radius = 0.5, tags = [myRect.tags.rectangleSegmentA001])
+```
+
+See how we use the tag `rectangleSegmentA001` in the `fillet` function outside
+the `rect` function. This is because the `rect` function is returning the
+sketch group that contains the tags.
+
+
+

docs/kcl-std/types/std-types-TaggedEdge.md

@@ -0,0 +1,17 @@
+---
+title: "TaggedEdge"
+subtitle: "Type in std::types"
+excerpt: "A tag which references a line, arc, or other edge in a sketch or an edge of a solid."
+layout: manual
+---
+
+A tag which references a line, arc, or other edge in a sketch or an edge of a solid.
+
+Created by using a tag declarator (see the docs for [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl)). Can be used where an [`Edge`](/docs/kcl-std/types/std-types-Edge) is
+required.
+
+If a line in a sketch is tagged and then the sketch is extruded, the tag is a [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) before
+extrusion and a [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) after extrusion.
+
+
+

docs/kcl-std/types/std-types-TaggedFace.md

@@ -0,0 +1,16 @@
+---
+title: "TaggedFace"
+subtitle: "Type in std::types"
+excerpt: "A tag which references a face of a solid, including the distinguished tags `START` and `END`."
+layout: manual
+---
+
+A tag which references a face of a solid, including the distinguished tags `START` and `END`.
+
+Created by using a tag declarator (see the docs for [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl)).
+
+If a line in a sketch is tagged and then the sketch is extruded, the tag is a [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) before
+extrusion and a [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace) after extrusion.
+
+
+

docs/kcl-std/types/std-types-tag.md

@@ -1,109 +1,19 @@
 ---
 title: "tag"
 subtitle: "Type in std::types"
-excerpt: "Tags are used to give a name (tag) to a specific path."
+excerpt: "Reference a previously created tag. Used much like a variable."
 layout: manual
 ---
 
-Tags are used to give a name (tag) to a specific path.
+**WARNING:** This type is deprecated.
 
-### Tag Declaration
+Reference a previously created tag. Used much like a variable.
 
-The syntax for declaring a tag is `$myTag` you would use it in the following
+```kcl
-way:
+type tag = TaggedEdge
-
-```js
-startSketchOn(XZ)
-  |> startProfile(at = origin)
-  |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
-  |> angledLine(
-       angle = segAng(rectangleSegmentA001) - 90deg,
-       length = 196.99,
-       tag = $rectangleSegmentB001,
-     )
-  |> angledLine(
-       angle = segAng(rectangleSegmentA001),
-       length = -segLen(rectangleSegmentA001),
-       tag = $rectangleSegmentC001,
-     )
-  |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-  |> close()
 ```
 
-### Tag Identifier
+Prefer to use [`TaggedEdge`](/docs/kcl-std/types/std-types-TaggedEdge) or [`TaggedFace`](/docs/kcl-std/types/std-types-TaggedFace). For more details on tags, see the docs for [`TagDecl`](/docs/kcl-std/types/std-types-TagDecl).
-
-As per the example above you can use the tag identifier to get a reference to the
-tagged object. The syntax for this is `myTag`.
-
-In the example above we use the tag identifier to get the angle of the segment
-`segAng(rectangleSegmentA001)`.
-
-### Tag Scope
-
-Tags are scoped globally if in the root context meaning in this example you can
-use the tag `rectangleSegmentA001` in any function or expression in the file.
-
-However if the code was written like this:
-
-```js
-fn rect(origin) {
-  return startSketchOn(XZ)
-    |> startProfile(at = origin)
-    |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
-    |> angledLine(
-         angle = segAng(rectangleSegmentA001) - 90,
-         length = 196.99,
-         tag = $rectangleSegmentB001)
-    |> angledLine(
-         angle = segAng(rectangleSegmentA001),
-         length = -segLen(rectangleSegmentA001),
-         tag = $rectangleSegmentC001
-       )
-    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-    |> close()
-}
-
-rect(origin = [0, 0])
-rect(origin = [20, 0])
-```
-
-Those tags would only be available in the `rect` function and not globally.
-
-However you likely want to use those tags somewhere outside the `rect` function.
-
-Tags are accessible through the sketch group they are declared in.
-For example the following code works.
-
-```js
-fn rect(origin) {
-  return startSketchOn(XZ)
-    |> startProfile(at = origin)
-    |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
-    |> angledLine(
-         angle = segAng(rectangleSegmentA001) - 90deg,
-         length = 196.99
-         tag = $rectangleSegmentB001,
-       )
-    |> angledLine(
-         angle = segAng(rectangleSegmentA001),
-         length = -segLen(rectangleSegmentA001)
-         tag = $rectangleSegmentC001,
-       )
-    |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
-    |> close()
-}
-
-rect(origin = [0, 0])
-myRect = rect(origin = [20, 0])
-
-myRect
-  |> extrude(length = 10)
-  |> fillet(radius = 0.5, tags = [myRect.tags.rectangleSegmentA001])
-```
-
-See how we use the tag `rectangleSegmentA001` in the `fillet` function outside
-the `rect` function. This is because the `rect` function is returning the
-sketch group that contains the tags.
 
 
 

e2e/playwright/projects.spec.ts

@@ -170,7 +170,7 @@ test(
       // error text on hover
       await page.hover('.cm-lint-marker-error')
       const crypticErrorText =
-        'tag requires a value with type `tag`, but found a value with type `string`.'
+        'tag requires a value with type `TagDecl`, but found a value with type `string`.'
       await expect(page.getByText(crypticErrorText).first()).toBeVisible()
 
       // black pixel means the scene has been cleared.
@@ -369,7 +369,7 @@ test(
       // error text on hover
       await page.hover('.cm-lint-marker-error')
       const crypticErrorText =
-        'tag requires a value with type `tag`, but found a value with type `string`.'
+        'tag requires a value with type `TagDecl`, but found a value with type `string`.'
       await expect(page.getByText(crypticErrorText).first()).toBeVisible()
 
       // black pixel means the scene has been cleared.
@@ -408,7 +408,7 @@ test(
     // error text on hover
     await page.hover('.cm-lint-marker-error')
     const crypticErrorText =
-      'tag requires a value with type `tag`, but found a value with type `string`.'
+      'tag requires a value with type `TagDecl`, but found a value with type `string`.'
     await expect(page.getByText(crypticErrorText).first()).toBeVisible()
   }
 )

rust/kcl-lib/e2e/executor/main.rs

@@ -1232,7 +1232,7 @@ secondSketch = startSketchOn(part001, face = '')
     let err = err.as_kcl_error().unwrap();
     assert_eq!(
         err.message(),
-        "face requires a value with type `tag`, but found a value with type `string`."
+        "face requires a value with type `TaggedFace`, but found a value with type `string`."
     );
 }
 

rust/kcl-lib/src/docs/gen_std_tests.rs

@@ -351,7 +351,7 @@ fn docs_for_type(ty: &str, kcl_std: &ModData) -> Option<String> {
     None
 }
 
-fn generate_const_from_kcl(cnst: &ConstData, file_name: String, example_name: String) -> Result<()> {
+fn generate_const_from_kcl(cnst: &ConstData, file_name: String, example_name: String, kcl_std: &ModData) -> Result<()> {
     if cnst.properties.doc_hidden {
         return Ok(());
     }
@@ -371,11 +371,13 @@ fn generate_const_from_kcl(cnst: &ConstData, file_name: String, example_name: St
         "description": cnst.description,
         "deprecated": cnst.properties.deprecated,
         "type_": cnst.ty,
+        "type_desc": cnst.ty.as_ref().map(|t| docs_for_type(t, kcl_std).unwrap_or_default()),
         "examples": examples,
         "value": cnst.value.as_deref().unwrap_or(""),
     });
 
     let output = hbs.render("const", &data)?;
+    let output = cleanup_types(&output, kcl_std);
     expectorate::assert_contents(format!("../../docs/kcl-std/{}.md", file_name), &output);
 
     Ok(())
@@ -529,7 +531,8 @@ fn cleanup_type_string(input: &str, fmt_for_text: bool, kcl_std: &ModData) -> St
                 format!("[{prefix}{ty}{suffix}](/docs/kcl-std/types/std-types-number)")
             } else if fmt_for_text && ty.starts_with("fn") {
                 format!("[{prefix}{ty}{suffix}](/docs/kcl-std/types/std-types-fn)")
-            } else if fmt_for_text && matches!(kcl_std.find_by_name(ty), Some(DocData::Ty(_))) {
+            // Special case for `tag` because it exists as a type but is deprecated and mostly used as an arg name
+            } else if fmt_for_text && matches!(kcl_std.find_by_name(ty), Some(DocData::Ty(_))) && ty != "tag" {
                 format!("[{prefix}{ty}{suffix}](/docs/kcl-std/types/std-types-{ty})")
             } else {
                 format!("{prefix}{ty}{suffix}")
@@ -550,7 +553,7 @@ fn test_generate_stdlib_markdown_docs() {
     for d in kcl_std.all_docs() {
         match d {
             DocData::Fn(f) => generate_function_from_kcl(f, d.file_name(), d.example_name(), &kcl_std).unwrap(),
-            DocData::Const(c) => generate_const_from_kcl(c, d.file_name(), d.example_name()).unwrap(),
+            DocData::Const(c) => generate_const_from_kcl(c, d.file_name(), d.example_name(), &kcl_std).unwrap(),
             DocData::Ty(t) => generate_type_from_kcl(t, d.file_name(), d.example_name(), &kcl_std).unwrap(),
             DocData::Mod(m) => generate_mod_from_kcl(m, d.file_name()).unwrap(),
         }

rust/kcl-lib/src/docs/kcl_doc.rs

@@ -359,6 +359,7 @@ impl ConstData {
                     crate::parsing::ast::types::LiteralValue::Bool { .. } => "boolean".to_owned(),
                 }),
             ),
+            crate::parsing::ast::types::Expr::AscribedExpression(e) => (None, Some(e.ty.to_string())),
             _ => (None, None),
         };
 
@@ -831,7 +832,7 @@ impl ArgData {
             Some("Edge") => Some((index, format!(r#"{label}${{{index}:tag_or_edge_fn}}"#))),
             Some("[Edge; 1+]") => Some((index, format!(r#"{label}[${{{index}:tag_or_edge_fn}}]"#))),
             Some("Plane") | Some("Solid | Plane") => Some((index, format!(r#"{label}${{{}:XY}}"#, index))),
-            Some("[tag; 2]") => Some((
+            Some("[TaggedFace; 2]") => Some((
                 index + 1,
                 format!(r#"{label}[${{{}:tag}}, ${{{}:tag}}]"#, index, index + 1),
             )),
@@ -1098,7 +1099,7 @@ trait ApplyMeta {
                                 self.impl_kind(annotations::Impl::from_str(s).unwrap());
                             }
                         }
-                        "deprecated" => {
+                        annotations::DEPRECATED => {
                             if let Some(b) = p.value.literal_bool() {
                                 self.deprecated(b);
                             }

rust/kcl-lib/src/docs/mod.rs

@@ -281,8 +281,8 @@ mod tests {
   length: number(Length),
   symmetric?: bool,
   bidirectionalLength?: number(Length),
-  tagStart?: tag,
+  tagStart?: TagDecl,
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+]"#
         );
     }

rust/kcl-lib/src/docs/templates/const.hbs

@@ -17,6 +17,12 @@ layout: manual
 
 {{{description}}}
 
+{{#if type_}}
+### Type
+
+`{{type_}}`{{#if type_desc}} - {{{firstLine type_desc}}}{{/if}}
+
+{{/if}}
 {{#if examples}}
 ### Examples
 

rust/kcl-lib/src/execution/annotations.rs

@@ -32,6 +32,8 @@ pub(crate) const IMPL_KCL: &str = "kcl";
 pub(crate) const IMPL_PRIMITIVE: &str = "primitive";
 pub(super) const IMPL_VALUES: [&str; 3] = [IMPL_RUST, IMPL_KCL, IMPL_PRIMITIVE];
 
+pub(crate) const DEPRECATED: &str = "deprecated";
+
 #[derive(Clone, Copy, Eq, PartialEq, Debug, Default)]
 pub enum Impl {
     #[default]

rust/kcl-lib/src/execution/types.rs

@@ -84,16 +84,16 @@ impl RuntimeType {
         RuntimeType::Primitive(PrimitiveType::Face)
     }
 
-    pub fn tag() -> Self {
-        RuntimeType::Primitive(PrimitiveType::Tag)
-    }
-
     pub fn tag_decl() -> Self {
         RuntimeType::Primitive(PrimitiveType::TagDecl)
     }
 
-    pub fn tag_identifier() -> Self {
+    pub fn tagged_face() -> Self {
-        RuntimeType::Primitive(PrimitiveType::TagId)
+        RuntimeType::Primitive(PrimitiveType::TaggedFace)
+    }
+
+    pub fn tagged_edge() -> Self {
+        RuntimeType::Primitive(PrimitiveType::TaggedEdge)
     }
 
     pub fn bool() -> Self {
@@ -196,7 +196,7 @@ impl RuntimeType {
                 RuntimeType::Primitive(PrimitiveType::Number(ty))
             }
             AstPrimitiveType::Named { id } => Self::from_alias(&id.name, exec_state, source_range)?,
-            AstPrimitiveType::Tag => RuntimeType::Primitive(PrimitiveType::Tag),
+            AstPrimitiveType::TagDecl => RuntimeType::Primitive(PrimitiveType::TagDecl),
             AstPrimitiveType::ImportedGeometry => RuntimeType::Primitive(PrimitiveType::ImportedGeometry),
             AstPrimitiveType::Function(_) => RuntimeType::Primitive(PrimitiveType::Function),
         })
@@ -383,8 +383,8 @@ pub enum PrimitiveType {
     Number(NumericType),
     String,
     Boolean,
-    Tag,
+    TaggedEdge,
-    TagId,
+    TaggedFace,
     TagDecl,
     Sketch,
     Solid,
@@ -416,9 +416,9 @@ impl PrimitiveType {
             PrimitiveType::Axis3d => "3d axes".to_owned(),
             PrimitiveType::ImportedGeometry => "imported geometries".to_owned(),
             PrimitiveType::Function => "functions".to_owned(),
-            PrimitiveType::Tag => "tags".to_owned(),
             PrimitiveType::TagDecl => "tag declarators".to_owned(),
-            PrimitiveType::TagId => "tag identifiers".to_owned(),
+            PrimitiveType::TaggedEdge => "tagged edges".to_owned(),
+            PrimitiveType::TaggedFace => "tagged faces".to_owned(),
         }
     }
 
@@ -426,7 +426,8 @@ impl PrimitiveType {
         match (self, other) {
             (_, PrimitiveType::Any) => true,
             (PrimitiveType::Number(n1), PrimitiveType::Number(n2)) => n1.subtype(n2),
-            (PrimitiveType::TagId, PrimitiveType::Tag) | (PrimitiveType::TagDecl, PrimitiveType::Tag) => true,
+            (PrimitiveType::TaggedEdge, PrimitiveType::TaggedFace)
+            | (PrimitiveType::TaggedEdge, PrimitiveType::Edge) => true,
             (t1, t2) => t1 == t2,
         }
     }
@@ -442,9 +443,9 @@ impl fmt::Display for PrimitiveType {
             PrimitiveType::Number(NumericType::Any) => write!(f, "number(any units)"),
             PrimitiveType::String => write!(f, "string"),
             PrimitiveType::Boolean => write!(f, "bool"),
-            PrimitiveType::Tag => write!(f, "tag"),
             PrimitiveType::TagDecl => write!(f, "tag declarator"),
-            PrimitiveType::TagId => write!(f, "tag identifier"),
+            PrimitiveType::TaggedEdge => write!(f, "tagged edge"),
+            PrimitiveType::TaggedFace => write!(f, "tagged face"),
             PrimitiveType::Sketch => write!(f, "Sketch"),
             PrimitiveType::Solid => write!(f, "Solid"),
             PrimitiveType::Plane => write!(f, "Plane"),
@@ -1207,6 +1208,17 @@ impl KclValue {
                 KclValue::TagIdentifier { .. } => Ok(self.clone()),
                 _ => Err(self.into()),
             },
+            PrimitiveType::TaggedEdge => match self {
+                KclValue::TagIdentifier { .. } => Ok(self.clone()),
+                _ => Err(self.into()),
+            },
+            PrimitiveType::TaggedFace => match self {
+                KclValue::TagIdentifier { .. } => Ok(self.clone()),
+                s @ KclValue::String { value, .. } if ["start", "end", "START", "END"].contains(&&**value) => {
+                    Ok(s.clone())
+                }
+                _ => Err(self.into()),
+            },
             PrimitiveType::Axis2d => match self {
                 KclValue::Object { value: values, meta } => {
                     if values
@@ -1295,23 +1307,10 @@ impl KclValue {
                 KclValue::Function { .. } => Ok(self.clone()),
                 _ => Err(self.into()),
             },
-            PrimitiveType::TagId => match self {
-                KclValue::TagIdentifier { .. } => Ok(self.clone()),
-                _ => Err(self.into()),
-            },
             PrimitiveType::TagDecl => match self {
                 KclValue::TagDeclarator { .. } => Ok(self.clone()),
                 _ => Err(self.into()),
             },
-            PrimitiveType::Tag => match self {
-                KclValue::TagDeclarator { .. } | KclValue::TagIdentifier { .. } | KclValue::Uuid { .. } => {
-                    Ok(self.clone())
-                }
-                s @ KclValue::String { value, .. } if ["start", "end", "START", "END"].contains(&&**value) => {
-                    Ok(s.clone())
-                }
-                _ => Err(self.into()),
-            },
         }
     }
 
@@ -1501,9 +1500,9 @@ impl KclValue {
             KclValue::HomArray { ty, value, .. } => {
                 Some(RuntimeType::Array(Box::new(ty.clone()), ArrayLen::Known(value.len())))
             }
-            KclValue::TagIdentifier(_) => Some(RuntimeType::Primitive(PrimitiveType::TagId)),
+            KclValue::TagIdentifier(_) => Some(RuntimeType::Primitive(PrimitiveType::TaggedEdge)),
             KclValue::TagDeclarator(_) => Some(RuntimeType::Primitive(PrimitiveType::TagDecl)),
-            KclValue::Uuid { .. } => Some(RuntimeType::Primitive(PrimitiveType::Tag)),
+            KclValue::Uuid { .. } => Some(RuntimeType::Primitive(PrimitiveType::Edge)),
             KclValue::Function { .. } => Some(RuntimeType::Primitive(PrimitiveType::Function)),
             KclValue::Module { .. } | KclValue::KclNone { .. } | KclValue::Type { .. } => None,
         }

rust/kcl-lib/src/parsing/ast/digest.rs

@@ -223,7 +223,7 @@ impl PrimitiveType {
             PrimitiveType::String => hasher.update(b"string"),
             PrimitiveType::Number(suffix) => hasher.update(suffix.digestable_id()),
             PrimitiveType::Boolean => hasher.update(b"bool"),
-            PrimitiveType::Tag => hasher.update(b"tag"),
+            PrimitiveType::TagDecl => hasher.update(b"TagDecl"),
             PrimitiveType::ImportedGeometry => hasher.update(b"ImportedGeometry"),
             PrimitiveType::Function(f) => hasher.update(f.compute_digest()),
         }

rust/kcl-lib/src/parsing/ast/types/mod.rs

@@ -3151,8 +3151,8 @@ pub enum PrimitiveType {
     /// A boolean type.
     #[serde(rename = "bool")]
     Boolean,
-    /// A tag.
+    /// A tag declaration.
-    Tag,
+    TagDecl,
     /// Imported from other CAD system.
     ImportedGeometry,
     /// `fn`, type of functions.
@@ -3167,7 +3167,7 @@ impl PrimitiveType {
             ("any", None) => Some(PrimitiveType::Any),
             ("string", None) => Some(PrimitiveType::String),
             ("bool", None) => Some(PrimitiveType::Boolean),
-            ("tag", None) => Some(PrimitiveType::Tag),
+            ("TagDecl", None) => Some(PrimitiveType::TagDecl),
             ("number", None) => Some(PrimitiveType::Number(NumericSuffix::None)),
             ("number", Some(s)) => Some(PrimitiveType::Number(s)),
             ("ImportedGeometry", None) => Some(PrimitiveType::ImportedGeometry),
@@ -3184,7 +3184,7 @@ impl PrimitiveType {
             PrimitiveType::ImportedGeometry => "imported geometries".to_owned(),
             PrimitiveType::Function(_) => "functions".to_owned(),
             PrimitiveType::Named { id } => format!("`{}`s", id.name),
-            PrimitiveType::Tag => "tags".to_owned(),
+            PrimitiveType::TagDecl => "tag declarations".to_owned(),
         }
     }
 }
@@ -3202,7 +3202,7 @@ impl fmt::Display for PrimitiveType {
             }
             PrimitiveType::String => write!(f, "string"),
             PrimitiveType::Boolean => write!(f, "bool"),
-            PrimitiveType::Tag => write!(f, "tag"),
+            PrimitiveType::TagDecl => write!(f, "TagDecl"),
             PrimitiveType::ImportedGeometry => write!(f, "ImportedGeometry"),
             PrimitiveType::Function(t) => {
                 write!(f, "fn")?;

rust/kcl-lib/src/std/edge.rs

@@ -11,12 +11,13 @@ use crate::{
         types::{ArrayLen, RuntimeType},
         ExecState, ExtrudeSurface, KclValue, ModelingCmdMeta, TagIdentifier,
     },
-    std::Args,
+    std::{sketch::FaceTag, Args},
+    SourceRange,
 };
 
 /// Get the opposite edge to the edge given.
 pub async fn get_opposite_edge(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let input_edge = args.get_unlabeled_kw_arg("edge", &RuntimeType::tag_identifier(), exec_state)?;
+    let input_edge = args.get_unlabeled_kw_arg("edge", &RuntimeType::tagged_edge(), exec_state)?;
 
     let edge = inner_get_opposite_edge(input_edge, exec_state, args.clone()).await?;
     Ok(KclValue::Uuid {
@@ -64,7 +65,7 @@ async fn inner_get_opposite_edge(
 
 /// Get the next adjacent edge to the edge given.
 pub async fn get_next_adjacent_edge(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let input_edge = args.get_unlabeled_kw_arg("edge", &RuntimeType::tag_identifier(), exec_state)?;
+    let input_edge = args.get_unlabeled_kw_arg("edge", &RuntimeType::tagged_edge(), exec_state)?;
 
     let edge = inner_get_next_adjacent_edge(input_edge, exec_state, args.clone()).await?;
     Ok(KclValue::Uuid {
@@ -121,7 +122,7 @@ async fn inner_get_next_adjacent_edge(
 
 /// Get the previous adjacent edge to the edge given.
 pub async fn get_previous_adjacent_edge(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let input_edge = args.get_unlabeled_kw_arg("edge", &RuntimeType::tag_identifier(), exec_state)?;
+    let input_edge = args.get_unlabeled_kw_arg("edge", &RuntimeType::tagged_edge(), exec_state)?;
 
     let edge = inner_get_previous_adjacent_edge(input_edge, exec_state, args.clone()).await?;
     Ok(KclValue::Uuid {
@@ -177,13 +178,33 @@ async fn inner_get_previous_adjacent_edge(
 
 /// Get the shared edge between two faces.
 pub async fn get_common_edge(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let faces: Vec<TagIdentifier> = args.get_kw_arg(
+    let mut faces: Vec<FaceTag> = args.get_kw_arg(
         "faces",
-        &RuntimeType::Array(Box::new(RuntimeType::tag_identifier()), ArrayLen::Known(2)),
+        &RuntimeType::Array(Box::new(RuntimeType::tagged_face()), ArrayLen::Known(2)),
         exec_state,
     )?;
 
-    let edge = inner_get_common_edge(faces, exec_state, args.clone()).await?;
+    if faces.len() != 2 {
+        return Err(KclError::new_type(KclErrorDetails::new(
+            "getCommonEdge requires exactly two tags for faces".to_owned(),
+            vec![args.source_range],
+        )));
+    }
+
+    fn into_tag(face: FaceTag, source_range: SourceRange) -> Result<TagIdentifier, KclError> {
+        match face {
+            FaceTag::StartOrEnd(_) => Err(KclError::new_type(KclErrorDetails::new(
+                "getCommonEdge requires a tagged face, it cannot use `START` or `END` faces".to_owned(),
+                vec![source_range],
+            ))),
+            FaceTag::Tag(tag_identifier) => Ok(*tag_identifier),
+        }
+    }
+
+    let face2 = into_tag(faces.pop().unwrap(), args.source_range)?;
+    let face1 = into_tag(faces.pop().unwrap(), args.source_range)?;
+
+    let edge = inner_get_common_edge(face1, face2, exec_state, args.clone()).await?;
     Ok(KclValue::Uuid {
         value: edge,
         meta: vec![args.source_range.into()],
@@ -191,7 +212,8 @@ pub async fn get_common_edge(exec_state: &mut ExecState, args: Args) -> Result<K
 }
 
 async fn inner_get_common_edge(
-    faces: Vec<TagIdentifier>,
+    face1: TagIdentifier,
+    face2: TagIdentifier,
     exec_state: &mut ExecState,
     args: Args,
 ) -> Result<Uuid, KclError> {
@@ -200,17 +222,11 @@ async fn inner_get_common_edge(
         return Ok(id);
     }
 
-    if faces.len() != 2 {
+    let first_face_id = args.get_adjacent_face_to_tag(exec_state, &face1, false).await?;
-        return Err(KclError::new_type(KclErrorDetails::new(
+    let second_face_id = args.get_adjacent_face_to_tag(exec_state, &face2, false).await?;
-            "getCommonEdge requires exactly two tags for faces".to_string(),
-            vec![args.source_range],
-        )));
-    }
-    let first_face_id = args.get_adjacent_face_to_tag(exec_state, &faces[0], false).await?;
-    let second_face_id = args.get_adjacent_face_to_tag(exec_state, &faces[1], false).await?;
 
-    let first_tagged_path = args.get_tag_engine_info(exec_state, &faces[0])?.clone();
+    let first_tagged_path = args.get_tag_engine_info(exec_state, &face1)?.clone();
-    let second_tagged_path = args.get_tag_engine_info(exec_state, &faces[1])?;
+    let second_tagged_path = args.get_tag_engine_info(exec_state, &face2)?;
 
     if first_tagged_path.sketch != second_tagged_path.sketch {
         return Err(KclError::new_type(KclErrorDetails::new(
@@ -252,7 +268,7 @@ async fn inner_get_common_edge(
         KclError::new_type(KclErrorDetails::new(
             format!(
                 "No common edge was found between `{}` and `{}`",
-                faces[0].value, faces[1].value
+                face1.value, face2.value
             ),
             vec![args.source_range],
         ))

rust/kcl-lib/src/std/mod.rs

@@ -440,6 +440,8 @@ pub(crate) fn std_ty(path: &str, fn_name: &str) -> (PrimitiveType, StdFnProps) {
         ("types", "Edge") => (PrimitiveType::Edge, StdFnProps::default("std::types::Edge")),
         ("types", "Axis2d") => (PrimitiveType::Axis2d, StdFnProps::default("std::types::Axis2d")),
         ("types", "Axis3d") => (PrimitiveType::Axis3d, StdFnProps::default("std::types::Axis3d")),
+        ("types", "TaggedEdge") => (PrimitiveType::TaggedEdge, StdFnProps::default("std::types::TaggedEdge")),
+        ("types", "TaggedFace") => (PrimitiveType::TaggedFace, StdFnProps::default("std::types::TaggedFace")),
         _ => unreachable!(),
     }
 }

rust/kcl-lib/src/std/segment.rs

@@ -15,7 +15,7 @@ use crate::{
 
 /// Returns the point at the end of the given segment.
 pub async fn segment_end(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let pt = inner_segment_end(&tag, exec_state, args.clone())?;
 
     args.make_kcl_val_from_point([pt[0].n, pt[1].n], pt[0].ty.clone())
@@ -38,7 +38,7 @@ fn inner_segment_end(tag: &TagIdentifier, exec_state: &mut ExecState, args: Args
 
 /// Returns the segment end of x.
 pub async fn segment_end_x(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let result = inner_segment_end_x(&tag, exec_state, args.clone())?;
 
     Ok(args.make_user_val_from_f64_with_type(result))
@@ -58,7 +58,7 @@ fn inner_segment_end_x(tag: &TagIdentifier, exec_state: &mut ExecState, args: Ar
 
 /// Returns the segment end of y.
 pub async fn segment_end_y(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let result = inner_segment_end_y(&tag, exec_state, args.clone())?;
 
     Ok(args.make_user_val_from_f64_with_type(result))
@@ -78,7 +78,7 @@ fn inner_segment_end_y(tag: &TagIdentifier, exec_state: &mut ExecState, args: Ar
 
 /// Returns the point at the start of the given segment.
 pub async fn segment_start(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let pt = inner_segment_start(&tag, exec_state, args.clone())?;
 
     args.make_kcl_val_from_point([pt[0].n, pt[1].n], pt[0].ty.clone())
@@ -101,7 +101,7 @@ fn inner_segment_start(tag: &TagIdentifier, exec_state: &mut ExecState, args: Ar
 
 /// Returns the segment start of x.
 pub async fn segment_start_x(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let result = inner_segment_start_x(&tag, exec_state, args.clone())?;
 
     Ok(args.make_user_val_from_f64_with_type(result))
@@ -121,7 +121,7 @@ fn inner_segment_start_x(tag: &TagIdentifier, exec_state: &mut ExecState, args:
 
 /// Returns the segment start of y.
 pub async fn segment_start_y(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let result = inner_segment_start_y(&tag, exec_state, args.clone())?;
 
     Ok(args.make_user_val_from_f64_with_type(result))
@@ -186,7 +186,7 @@ fn inner_last_segment_y(sketch: Sketch, args: Args) -> Result<TyF64, KclError> {
 
 /// Returns the length of the segment.
 pub async fn segment_length(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
     let result = inner_segment_length(&tag, exec_state, args.clone())?;
     Ok(args.make_user_val_from_f64_with_type(result))
 }
@@ -205,7 +205,7 @@ fn inner_segment_length(tag: &TagIdentifier, exec_state: &mut ExecState, args: A
 
 /// Returns the angle of the segment.
 pub async fn segment_angle(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
 
     let result = inner_segment_angle(&tag, exec_state, args.clone())?;
     Ok(args.make_user_val_from_f64_with_type(TyF64::new(result, NumericType::degrees())))
@@ -227,7 +227,7 @@ fn inner_segment_angle(tag: &TagIdentifier, exec_state: &mut ExecState, args: Ar
 
 /// Returns the angle coming out of the end of the segment in degrees.
 pub async fn tangent_to_end(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
-    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tag_identifier(), exec_state)?;
+    let tag: TagIdentifier = args.get_unlabeled_kw_arg("tag", &RuntimeType::tagged_edge(), exec_state)?;
 
     let result = inner_tangent_to_end(&tag, exec_state, args.clone()).await?;
     Ok(args.make_user_val_from_f64_with_type(TyF64::new(result, NumericType::degrees())))

rust/kcl-lib/src/std/shell.rs

@@ -20,7 +20,7 @@ pub async fn shell(exec_state: &mut ExecState, args: Args) -> Result<KclValue, K
     let thickness: TyF64 = args.get_kw_arg("thickness", &RuntimeType::length(), exec_state)?;
     let faces = args.get_kw_arg(
         "faces",
-        &RuntimeType::Array(Box::new(RuntimeType::tag()), ArrayLen::Minimum(1)),
+        &RuntimeType::Array(Box::new(RuntimeType::tagged_face()), ArrayLen::Minimum(1)),
         exec_state,
     )?;
 

rust/kcl-lib/src/std/sketch.rs

@@ -684,7 +684,7 @@ async fn inner_angled_line_to_y(
 pub async fn angled_line_that_intersects(exec_state: &mut ExecState, args: Args) -> Result<KclValue, KclError> {
     let sketch = args.get_unlabeled_kw_arg("sketch", &RuntimeType::Primitive(PrimitiveType::Sketch), exec_state)?;
     let angle: TyF64 = args.get_kw_arg("angle", &RuntimeType::angle(), exec_state)?;
-    let intersect_tag: TagIdentifier = args.get_kw_arg("intersectTag", &RuntimeType::tag_identifier(), exec_state)?;
+    let intersect_tag: TagIdentifier = args.get_kw_arg("intersectTag", &RuntimeType::tagged_edge(), exec_state)?;
     let offset = args.get_kw_arg_opt("offset", &RuntimeType::length(), exec_state)?;
     let tag: Option<TagNode> = args.get_kw_arg_opt("tag", &RuntimeType::tag_decl(), exec_state)?;
     let new_sketch =
@@ -776,7 +776,7 @@ pub async fn start_sketch_on(exec_state: &mut ExecState, args: Args) -> Result<K
         &RuntimeType::Union(vec![RuntimeType::solid(), RuntimeType::plane()]),
         exec_state,
     )?;
-    let face = args.get_kw_arg_opt("face", &RuntimeType::tag(), exec_state)?;
+    let face = args.get_kw_arg_opt("face", &RuntimeType::tagged_face(), exec_state)?;
 
     match inner_start_sketch_on(data, face, exec_state, &args).await? {
         SketchSurface::Plane(value) => Ok(KclValue::Plane { value }),

rust/kcl-lib/std/prelude.kcl

@@ -64,10 +64,10 @@ export Z = {
 }: Axis3d
 
 /// Identifies the starting face of an extrusion. I.e., the face which is extruded.
-export START = 'start'
+export START = 'start': TaggedFace
 
 /// Identifies the ending face of an extrusion. I.e., the new face created by an extrusion.
-export END = 'end'
+export END = 'end': TaggedFace
 
 /// Create a helix.
 ///

rust/kcl-lib/std/sketch.kcl

@@ -186,7 +186,7 @@ export fn startSketchOn(
   /// Profile whose start is being used.
   @planeOrSolid: Solid | Plane,
   /// Identify a face of a solid if a solid is specified as the input argument (`planeOrSolid`).
-  face?: tag,
+  face?: TaggedFace,
 ): Plane | Face {}
 
 /// Start a new profile at a given point.
@@ -231,7 +231,7 @@ export fn startProfile(
   @(snippetArray = ["0", "0"])
   at: Point2d,
   /// Tag this first starting point.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Construct a 2-dimensional circle, of the specified radius, centered at
@@ -268,7 +268,7 @@ export fn circle(
   @(includeInSnippet = true)
   diameter?: number(Length),
   /// Create a new tag which refers to this circle.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Extend a 2-dimensional sketch through a third dimension in order to
@@ -375,9 +375,9 @@ export fn extrude(
   /// If specified, will also extrude in the opposite direction to 'distance' to the specified distance. If 'symmetric' is true, this value is ignored.
   bidirectionalLength?: number(Length),
   /// A named tag for the face at the start of the extrusion, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the extrusion, i.e. the new face created by extruding the original sketch.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+] {}
 
 /// Works just like the `extrude` command, but also twists the sketch around
@@ -647,9 +647,9 @@ export fn revolve(
   /// If specified, will also revolve in the opposite direction to 'angle' to the specified angle. If 'symmetric' is true, this value is ignored.
   bidirectionalAngle?: number(Angle),
   /// A named tag for the face at the start of the revolve, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the revolve.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+] {}
 
 /// Just like `patternTransform`, but works on 2D sketches not 3D solids.
@@ -708,7 +708,7 @@ export fn patternTransform2d(
 @(impl = std_rust)
 export fn getOppositeEdge(
   /// The tag of the edge you want to find the opposite edge of.
-  @edge: tag,
+  @edge: TaggedEdge,
 ): Edge {}
 
 /// Get the next adjacent edge to the edge given.
@@ -742,7 +742,7 @@ export fn getOppositeEdge(
 @(impl = std_rust)
 export fn getNextAdjacentEdge(
   /// The tag of the edge you want to find the next adjacent edge of.
-  @edge: tag,
+  @edge: TaggedEdge,
 ): Edge {}
 
 /// Get the previous adjacent edge to the edge given.
@@ -776,7 +776,7 @@ export fn getNextAdjacentEdge(
 @(impl = std_rust)
 export fn getPreviousAdjacentEdge(
   /// The tag of the edge you want to find the previous adjacent edge of.
-  @edge: tag,
+  @edge: TaggedEdge,
 ): Edge {}
 
 /// Get the shared edge between two faces.
@@ -805,7 +805,7 @@ export fn getPreviousAdjacentEdge(
 @(impl = std_rust)
 export fn getCommonEdge(
   /// The tags of the faces you want to find the common edge between.
-  faces: [tag; 2],
+  faces: [TaggedFace; 2],
 ): Edge {}
 
 /// Construct a circle derived from 3 points.
@@ -826,7 +826,7 @@ export fn circleThreePoint(
   /// 3rd point to derive the circle.
   p3: Point2d,
   /// Identifier for the circle to reference elsewhere.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Create a regular polygon with the specified number of sides that is either inscribed or circumscribed around a circle of the specified radius.
@@ -984,9 +984,9 @@ export fn sweep(
   /// What is the sweep relative to? Can be either 'sketchPlane' or 'trajectoryCurve'.
   relativeTo?: string = 'trajectoryCurve',
   /// A named tag for the face at the start of the sweep, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the sweep.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): [Solid; 1+] {}
 
 /// Create a 3D surface or solid by interpolating between two or more sketches.
@@ -1068,9 +1068,9 @@ export fn loft(
   /// Tolerance for the loft operation.
   tolerance?: number(Length),
   /// A named tag for the face at the start of the loft, i.e. the original sketch.
-  tagStart?: tag,
+  tagStart?: TagDecl,
   /// A named tag for the face at the end of the loft.
-  tagEnd?: tag,
+  tagEnd?: TagDecl,
 ): Solid {}
 
 /// Repeat a 2-dimensional sketch along some dimension, with a dynamic amount
@@ -1184,7 +1184,7 @@ export fn patternCircular2d(
 @(impl = std_rust)
 export fn segEnd(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): Point2d {}
 
 /// Compute the ending point of the provided line segment along the 'x' axis.
@@ -1203,7 +1203,7 @@ export fn segEnd(
 @(impl = std_rust)
 export fn segEndX(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the ending point of the provided line segment along the 'y' axis.
@@ -1223,7 +1223,7 @@ export fn segEndX(
 @(impl = std_rust)
 export fn segEndY(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the starting point of the provided line segment.
@@ -1254,7 +1254,7 @@ export fn segEndY(
 @(impl = std_rust)
 export fn segStart(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): Point2d {}
 
 /// Compute the starting point of the provided line segment along the 'x' axis.
@@ -1273,7 +1273,7 @@ export fn segStart(
 @(impl = std_rust)
 export fn segStartX(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the starting point of the provided line segment along the 'y' axis.
@@ -1293,7 +1293,7 @@ export fn segStartX(
 @(impl = std_rust)
 export fn segStartY(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Extract the 'x' axis value of the last line segment in the provided 2-d sketch.
@@ -1356,7 +1356,7 @@ export fn lastSegY(
 @(impl = std_rust)
 export fn segLen(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Length) {}
 
 /// Compute the angle (in degrees) of the provided line segment.
@@ -1377,7 +1377,7 @@ export fn segLen(
 @(impl = std_rust)
 export fn segAng(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Angle) {}
 
 /// Returns the angle coming out of the end of the segment in degrees.
@@ -1454,7 +1454,7 @@ export fn segAng(
 @(impl = std_rust)
 export fn tangentToEnd(
   /// The line segment being queried by its tag.
-  @tag: tag,
+  @tag: TaggedEdge,
 ): number(Angle) {}
 
 /// Extract the provided 2-dimensional sketch's profile's origin value.
@@ -1526,7 +1526,7 @@ export fn involuteCircular(
   /// If reverse is true, the segment will start from the end of the involute, otherwise it will start from that start.
   reverse?: bool = false,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Extend the current sketch with a new straight line.
@@ -1563,7 +1563,7 @@ export fn line(
   @(includeInSnippet = true)
   end?: Point2d,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a line relative to the current origin to a specified distance away
@@ -1598,7 +1598,7 @@ export fn xLine(
   /// Which absolute X value should this line go to? Incompatible with `length`.
   endAbsolute?: number(Length),
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a line relative to the current origin to a specified distance away
@@ -1628,7 +1628,7 @@ export fn yLine(
   /// Which absolute Y value should this line go to? Incompatible with `length`.
   endAbsolute?: number(Length),
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a line segment relative to the current origin using the polar
@@ -1665,7 +1665,7 @@ export fn angledLine(
   /// Draw the line along the given angle until it reaches this point along the Y axis. Only one of `length`, `lengthX`, `lengthY`, `endAbsoluteX`, `endAbsoluteY` can be given.
   endAbsoluteY?: number(Length),
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw an angled line from the current origin, constructing a line segment
@@ -1694,11 +1694,11 @@ export fn angledLineThatIntersects(
   /// Which angle should the line be drawn at?
   angle: number(Angle),
   /// The tag of the line to intersect with.
-  intersectTag: tag,
+  intersectTag: TaggedEdge,
   /// The offset from the intersecting line.
   offset?: number(Length) = 0mm,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Construct a line segment from the current origin back to the profile's
@@ -1732,7 +1732,7 @@ export fn close(
   /// The sketch you want to close.
   @sketch: Sketch,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a curved line segment along an imaginary circle.
@@ -1789,7 +1789,7 @@ export fn arc(
   /// Where should this arc end? Requires `interiorAbsolute`. Incompatible with `angleStart` or `angleEnd`.
   endAbsolute?: Point2d,
   /// Create a new tag which refers to this arc.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Starting at the current sketch's origin, draw a curved line segment along
@@ -1862,7 +1862,7 @@ export fn tangentialArc(
   /// Offset of the arc. `radius` must be given. Incompatible with `end` and `endAbsolute`.
   angle?: number(Angle),
   /// Create a new tag which refers to this arc.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Draw a smooth, continuous, curved line segment from the current origin to
@@ -1910,7 +1910,7 @@ export fn bezierCurve(
   /// Coordinate on the plane at which this line should end.
   endAbsolute?: Point2d,
   /// Create a new tag which refers to this line.
-  tag?: tag,
+  tag?: TagDecl,
 ): Sketch {}
 
 /// Use a 2-dimensional sketch to cut a hole in another 2-dimensional sketch.

rust/kcl-lib/std/solid.kcl

@@ -73,7 +73,7 @@ export fn fillet(
   /// The tolerance for this fillet
   tolerance?: number(Length),
   /// Create a new tag which refers to this fillet
-  tag?: tag,
+  tag?: TagDecl,
 ): Solid {}
 
 /// Cut a straight transitional edge along a tagged path.
@@ -148,7 +148,7 @@ export fn chamfer(
   /// The paths you want to chamfer
   tags: [Edge; 1+],
   /// Create a new tag which refers to this chamfer
-  tag?: tag,
+  tag?: TagDecl,
 ): Solid {}
 
 /// Remove volume from a 3-dimensional shape such that a wall of the
@@ -304,7 +304,7 @@ export fn shell(
   /// The thickness of the shell
   thickness: number(Length),
   /// The faces you want removed
-  faces: [tag; 1+],
+  faces: [TaggedFace; 1+],
 ): [Solid] {}
 
 

rust/kcl-lib/std/types.kcl

@@ -65,7 +65,7 @@ export type string
 ///
 /// ### Tag Declaration
 ///
-/// The syntax for declaring a tag is `$myTag` you would use it in the following
+/// The syntax for declaring a tag is `$myTag`. You would use it in the following
 /// way:
 ///
 /// ```norun,inline
@@ -86,14 +86,6 @@ export type string
 ///   |> close()
 /// ```
 ///
-/// ### Tag Identifier
-///
-/// As per the example above you can use the tag identifier to get a reference to the 
-/// tagged object. The syntax for this is `myTag`.
-/// 
-/// In the example above we use the tag identifier to get the angle of the segment
-/// `segAng(rectangleSegmentA001)`.
-///
 /// ### Tag Scope
 ///
 /// Tags are scoped globally if in the root context meaning in this example you can 
@@ -109,7 +101,8 @@ export type string
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001) - 90,
 ///          length = 196.99,
-///          tag = $rectangleSegmentB001)
+///          tag = $rectangleSegmentB001
+///        )
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001),
 ///          length = -segLen(rectangleSegmentA001),
@@ -137,12 +130,12 @@ export type string
 ///     |> angledLine(angle = 0, length = 191.26, tag = $rectangleSegmentA001)
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001) - 90deg,
-///          length = 196.99
+///          length = 196.99,
 ///          tag = $rectangleSegmentB001,
 ///        )
 ///     |> angledLine(
 ///          angle = segAng(rectangleSegmentA001),
-///          length = -segLen(rectangleSegmentA001)
+///          length = -segLen(rectangleSegmentA001),
 ///          tag = $rectangleSegmentC001,
 ///        )
 ///     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
@@ -161,7 +154,32 @@ export type string
 /// the `rect` function. This is because the `rect` function is returning the
 /// sketch group that contains the tags.
 @(impl = primitive)
-export type tag
+export type TagDecl
+
+/// A tag which references a line, arc, or other edge in a sketch or an edge of a solid.
+///
+/// Created by using a tag declarator (see the docs for `TagDecl`). Can be used where an `Edge` is
+/// required.
+///
+/// If a line in a sketch is tagged and then the sketch is extruded, the tag is a `TaggedEdge` before
+/// extrusion and a `TaggedFace` after extrusion.
+@(impl = std_rust)
+export type TaggedEdge
+
+/// A tag which references a face of a solid, including the distinguished tags `START` and `END`.
+///
+/// Created by using a tag declarator (see the docs for `TagDecl`).
+///
+/// If a line in a sketch is tagged and then the sketch is extruded, the tag is a `TaggedEdge` before
+/// extrusion and a `TaggedFace` after extrusion.
+@(impl = std_rust)
+export type TaggedFace
+
+/// Reference a previously created tag. Used much like a variable.
+///
+/// Prefer to use `TaggedEdge` or `TaggedFace`. For more details on tags, see the docs for `TagDecl`.
+@(deprecated = true)
+export type tag = TaggedEdge
 
 /// Represents geometry which is defined using some other CAD system and imported into KCL.
 @(impl = primitive)

rust/kcl-lib/tests/panic_repro_cube/execution_error.snap

@@ -4,8 +4,8 @@ description: Error from executing panic_repro_cube.kcl
 ---
 KCL Semantic error
 
-  × semantic: This function expected the input argument to be tag identifier
+  × semantic: The input argument of `getNextAdjacentEdge` requires a value
-  │ but it's actually of type tag
+  │ with type `TaggedEdge`, but found a unique ID (uuid) (with type `Edge`).
     ╭─[43:5]
  42 │     // these double wrapped functions are the point of this test
  43 │     getNextAdjacentEdge(getNextAdjacentEdge(seg01)),
@@ -16,8 +16,9 @@ KCL Semantic error
     ╰────
   ╰─▶ KCL Semantic error
       
-        × semantic: This function expected the input argument to be tag
+        × semantic: The input argument of `getNextAdjacentEdge` requires a
-        │ identifier but it's actually of type tag
+        │ value with type `TaggedEdge`, but found a unique ID (uuid) (with
+        │ type `Edge`).
           ╭─[43:25]
        42 │     // these double wrapped functions are the point of this test
        43 │     getNextAdjacentEdge(getNextAdjacentEdge(seg01)),