Assemblies: Make Clone available in releases (#6538)

* Assemblies: Make Clone available in releases
Fixes #6537

* Lint

.github/workflows/cargo-bench.yml

@@ -26,12 +26,8 @@ name: cargo bench
 jobs:
   cargo-bench:
     name: cargo bench
-    runs-on:
-      - runs-on=${{ github.run_id }}
-      - runner=32cpu-linux-x64
-      - extras=s3-cache
+    runs-on: ubuntu-latest
     steps:
-      - uses: runs-on/action@v1
       - uses: actions/checkout@v4
       - name: Use correct Rust toolchain
         shell: bash

.github/workflows/cargo-test.yml

@@ -13,10 +13,14 @@ concurrency:
   cancel-in-progress: true
 name: cargo test
 jobs:
-  cargotest:
-    name: cargo test
-    runs-on: ubuntu-latest-8-cores
+  build-test-artifacts:
+    name: Build test artifacts
+    runs-on:
+      - runs-on=${{ github.run_id }}
+      - runner=8cpu-linux-x64
+      - extras=s3-cache
     steps:
+      - uses: runs-on/action@v1
       - uses: actions/create-github-app-token@v1
         id: app-token
         with:
@@ -39,7 +43,6 @@ jobs:
         env:
           GH_ACTIONS_AXIOM_TOKEN: ${{ secrets.GH_ACTIONS_AXIOM_TOKEN }}
           OS_NAME: ${{ env.OS_NAME }}
-      - uses: taiki-e/install-action@cargo-llvm-cov
       - uses: taiki-e/install-action@nextest
       - name: Install just
         uses: taiki-e/install-action@just
@@ -81,11 +84,10 @@ jobs:
         run: |
           set -euo pipefail
           cd rust
-          cargo nextest run --workspace --retries=2 --no-fail-fast --profile ci simulation_tests::kcl_samples 2>&1 | tee /tmp/github-actions.log
+          cargo nextest run --workspace --features artifact-graph --retries=2 --no-fail-fast --profile ci simulation_tests::kcl_samples 2>&1 | tee /tmp/github-actions.log
         env:
           KITTYCAD_API_TOKEN: ${{secrets.KITTYCAD_API_TOKEN}}
           RUST_BACKTRACE: full
-          RUST_MIN_STACK: 10485760000
       - name: Commit differences
         if: steps.path-changes.outputs.outside-kcl-samples == 'false' && steps.cargo-test-kcl-samples.outcome == 'failure'
         shell: bash
@@ -118,23 +120,67 @@ jobs:
           # Configure nextest when it's run by insta (via just).
           NEXTEST_PROFILE: ci
           RUST_BACKTRACE: full
-          RUST_MIN_STACK: 10485760000
-      - name: cargo test
-        if: steps.path-changes.outputs.outside-kcl-samples == 'true'
+      - name: Build and archive tests
+        run: |
+          cd rust
+          cargo nextest archive --workspace --features artifact-graph --archive-file nextest-archive.tar.zst
+      - name: Upload archive to workflow
+        uses: actions/upload-artifact@v4
+        with:
+          name: nextest-archive
+          path: rust/nextest-archive.tar.zst
+
+  run-test-artifacts:
+    name: cargo test (shard ${{ matrix.partitionIndex}})
+    runs-on:
+      - runs-on=${{ github.run_id }}
+      - runner=32cpu-linux-x64
+      - extras=s3-cache
+    needs: build-test-artifacts
+    strategy:
+      fail-fast: false
+      matrix:
+        partitionIndex: [1, 2, 3, 4, 5, 6]
+        partitionTotal: [6]
+    steps:
+      - uses: runs-on/action@v1
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.MODELING_APP_GH_APP_ID }}
+          private-key: ${{ secrets.MODELING_APP_GH_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+      - name: Use correct Rust toolchain
+        shell: bash
+        run: |
+          [ -e rust-toolchain.toml ] || cp rust/rust-toolchain.toml ./
+      - name: Install rust
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          cache: false # Configured below.
+      - name: Start Vector
+        run: .github/ci-cd-scripts/start-vector-ubuntu.sh
+        env:
+          GH_ACTIONS_AXIOM_TOKEN: ${{ secrets.GH_ACTIONS_AXIOM_TOKEN }}
+          OS_NAME: ${{ env.OS_NAME }}
+      - uses: taiki-e/install-action@nextest
+      - name: Download archive
+        uses: actions/download-artifact@v4
+        with:
+          name: nextest-archive
+      - name: Run tests
         shell: bash
         run: |-
+          cp nextest-archive.tar.zst rust/nextest-archive.tar.zst
+          ls -lah
           cd rust
-          cargo llvm-cov nextest --workspace --lcov --output-path lcov.info --retries=2 --no-fail-fast -P ci 2>&1 | tee /tmp/github-actions.log
+          cargo nextest run\
+           --retries=2 --no-fail-fast -P ci --archive-file nextest-archive.tar.zst \
+           --partition count:${{ matrix.partitionIndex}}/${{ matrix.partitionTotal }} \
+           2>&1 | tee /tmp/github-actions.log
         env:
           KITTYCAD_API_TOKEN: ${{secrets.KITTYCAD_API_TOKEN}}
-          RUST_MIN_STACK: 10485760000
-      - name: Upload to codecov.io
-        if: steps.path-changes.outputs.outside-kcl-samples == 'true'
-        uses: codecov/codecov-action@v5
-        with:
-          token: ${{secrets.CODECOV_TOKEN}}
-          fail_ci_if_error: true
-          flags: rust
-          verbose: true
-          files: lcov.info
 

.github/workflows/e2e-tests.yml

@@ -3,7 +3,6 @@ on:
   push:
     branches:
       - main
-      - all-e2e # this bypasses `fixme()` using `orRunWhenFullSuiteEnabled()`
   pull_request:
   schedule:
     - cron: 0 * * * *  # hourly
@@ -278,28 +277,42 @@ jobs:
     timeout-minutes: 60
     env:
       OS_NAME: ${{ contains(matrix.os, 'ubuntu') && 'ubuntu' || (contains(matrix.os, 'windows') && 'windows' || 'macos') }}
-    name: playwright:electron:${{ contains(matrix.os, 'ubuntu') && 'ubuntu' || (contains(matrix.os, 'windows') && 'windows' || 'macos') }}:${{ matrix.shardIndex }}:${{ matrix.shardTotal }}
+    name: playwright:electron:${{ contains(matrix.os, 'ubuntu') && 'ubuntu' || (contains(matrix.os, 'windows') && 'windows' || 'macos') }} (shard ${{ matrix.shardIndex }})
     strategy:
       fail-fast: false
       matrix:
         # TODO: enable namespace-profile-windows-latest once available
-        os:
-          - "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
-          - namespace-profile-macos-8-cores
-          - windows-latest-8-cores
-        shardIndex: [1, 2, 3, 4]
-        shardTotal: [4]
-        # Disable macos and windows tests on hourly e2e tests since we only care
-        # about server side changes.
-        # Technique from https://github.com/joaomcteixeira/python-project-skeleton/pull/31/files
-        isScheduled:
-          - ${{ github.event_name == 'schedule' }}
-        exclude:
+        include:
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 1
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 2
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 3
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 4
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 5
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 6
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 7
+            shardTotal: 8
+          - os: "runs-on=${{ github.run_id }}/family=i7ie.2xlarge/image=ubuntu22-full-x64"
+            shardIndex: 8
+            shardTotal: 8
           - os: namespace-profile-macos-8-cores
-            isScheduled: true
+            shardIndex: 1
+            shardTotal: 1
           - os: windows-latest-8-cores
-            isScheduled: true
-        # TODO: add ref here for main and latest release tag
+            shardIndex: 1
+            shardTotal: 1
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

.github/workflows/update-e2e-branch.yml

@@ -1,45 +0,0 @@
-name: update-e2e-branch
-
-# This is used to sync the `all-e2e` branch with the `main` branch for the
-# logic in the test utility `orRunWhenFullSuiteEnabled()` that allows all e2e
-# tests to run on a particular branch to analyze failures metrics in Axiom.
-
-on:
-  schedule:
-    - cron: '0 * * * *' # runs every hour
-
-permissions:
-  contents: write
-
-jobs:
-  update-branch:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/create-github-app-token@v1
-        id: app-token
-        with:
-          app-id: ${{ secrets.MODELING_APP_GH_APP_ID }}
-          private-key: ${{ secrets.MODELING_APP_GH_APP_PRIVATE_KEY }}
-          owner: ${{ github.repository_owner }}
-
-      - uses: actions/checkout@v4
-        with:
-          token: ${{ steps.app-token.outputs.token }}
-
-      - name: Sync with main
-        run: |
-          # Create the branch
-          git checkout all-e2e || git checkout -b all-e2e
-
-          # Reset to main
-          git fetch origin
-          git reset --hard origin/main
-
-          # Get a new SHA to prevent overwriting the commit status on main
-          git config --local user.email "github-actions[bot]@users.noreply.github.com"
-          git config --local user.name "github-actions[bot]"
-          git commit --allow-empty --message="[all-e2e] $(git log --max-count=1 --pretty=%B)"
-
-          # Overwrite the branch
-          git remote set-url origin https://x-access-token:${{ steps.app-token.outputs.token }}@github.com/${{ github.repository }}.git
-          git push --force origin all-e2e

.husky/pre-commit

@@ -0,0 +1 @@
+npm run fmt

.husky/pre-push

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npm run fmt-check

docs/kcl/angledLine.md

@@ -8,17 +8,17 @@ Draw a line segment relative to the current origin using the polar measure of so
 
 
 
-```js
+```kcl
 angledLine(
-  sketch: Sketch,
-  angle: number,
-  length?: number,
-  lengthX?: number,
-  lengthY?: number,
-  endAbsoluteX?: number,
-  endAbsoluteY?: number,
-  tag?: TagDeclarator,
-): Sketch
+  sketch: [Sketch](/docs/kcl/types/Sketch),
+  angle: [number](/docs/kcl/types/number),
+  length?: [number](/docs/kcl/types/number),
+  lengthX?: [number](/docs/kcl/types/number),
+  lengthY?: [number](/docs/kcl/types/number),
+  endAbsoluteX?: [number](/docs/kcl/types/number),
+  endAbsoluteY?: [number](/docs/kcl/types/number),
+  tag?: [TagDeclarator](/docs/kcl/types#tag-declaration),
+): [Sketch](/docs/kcl/types/Sketch)
 ```
 
 
@@ -33,7 +33,7 @@ angledLine(
 | `lengthY` | [`number`](/docs/kcl/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`](/docs/kcl/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`](/docs/kcl/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/types/tag) | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
+| `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
 
 ### Returns
 
@@ -42,9 +42,9 @@ angledLine(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> yLine(endAbsolute = 15)
   |> angledLine(angle = 30, length = 15)
   |> line(end = [8, -10])

docs/kcl/angledLineThatIntersects.md

@@ -8,14 +8,14 @@ Draw an angled line from the current origin, constructing a line segment such th
 
 
 
-```js
+```kcl
 angledLineThatIntersects(
-  sketch: Sketch,
-  angle: number,
-  intersectTag: TagIdentifier,
-  offset?: number,
-  tag?: TagDeclarator,
-): Sketch
+  sketch: [Sketch](/docs/kcl/types/Sketch),
+  angle: [number](/docs/kcl/types/number),
+  intersectTag: [TagIdentifier](/docs/kcl/types#tag-identifier),
+  offset?: [number](/docs/kcl/types/number),
+  tag?: [TagDeclarator](/docs/kcl/types#tag-declaration),
+): [Sketch](/docs/kcl/types/Sketch)
 ```
 
 
@@ -27,7 +27,7 @@ angledLineThatIntersects(
 | `angle` | [`number`](/docs/kcl/types/number) | Which angle should the line be drawn at? | Yes |
 | `intersectTag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The tag of the line to intersect with | Yes |
 | `offset` | [`number`](/docs/kcl/types/number) | The offset from the intersecting line. Defaults to 0. | No |
-| [`tag`](/docs/kcl/types/tag) | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
+| `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
 
 ### Returns
 
@@ -36,9 +36,9 @@ angledLineThatIntersects(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(endAbsolute = [5, 10])
   |> line(endAbsolute = [-10, 10], tag = $lineToIntersect)
   |> line(endAbsolute = [0, 20])

docs/kcl/assert.md

@@ -8,15 +8,15 @@ Check a value meets some expected conditions at runtime. Program terminates with
 
 
 
-```js
+```kcl
 assert(
-  actual: number,
-  isGreaterThan?: number,
-  isLessThan?: number,
-  isGreaterThanOrEqual?: number,
-  isLessThanOrEqual?: number,
-  isEqualTo?: number,
-  tolerance?: number,
+  actual: [number](/docs/kcl/types/number),
+  isGreaterThan?: [number](/docs/kcl/types/number),
+  isLessThan?: [number](/docs/kcl/types/number),
+  isGreaterThanOrEqual?: [number](/docs/kcl/types/number),
+  isLessThanOrEqual?: [number](/docs/kcl/types/number),
+  isEqualTo?: [number](/docs/kcl/types/number),
+  tolerance?: [number](/docs/kcl/types/number),
   error?: String,
 ): ()
 ```
@@ -42,7 +42,7 @@ assert(
 
 ### Examples
 
-```js
+```kcl
 n = 10
 assert(n, isEqualTo = 10)
 assert(

docs/kcl/assertIs.md

@@ -8,9 +8,9 @@ Asserts that a value is the boolean value true.
 
 
 
-```js
+```kcl
 assertIs(
-  actual: bool,
+  actual: [bool](/docs/kcl/types/bool),
   error?: String,
 ): ()
 ```
@@ -30,7 +30,7 @@ assertIs(
 
 ### Examples
 
-```js
+```kcl
 kclIsFun = true
 assertIs(kclIsFun)
 ```

docs/kcl/bezierCurve.md

@@ -8,14 +8,14 @@ Draw a smooth, continuous, curved line segment from the current origin to the de
 
 
 
-```js
+```kcl
 bezierCurve(
-  sketch: Sketch,
-  control1: [number],
-  control2: [number],
-  end: [number],
-  tag?: TagDeclarator,
-): Sketch
+  sketch: [Sketch](/docs/kcl/types/Sketch),
+  control1: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  control2: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  end: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  tag?: [TagDeclarator](/docs/kcl/types#tag-declaration),
+): [Sketch](/docs/kcl/types/Sketch)
 ```
 
 
@@ -27,7 +27,7 @@ bezierCurve(
 | `control1` | [`[number]`](/docs/kcl/types/number) | First control point for the cubic | Yes |
 | `control2` | [`[number]`](/docs/kcl/types/number) | Second control point for the cubic | Yes |
 | `end` | [`[number]`](/docs/kcl/types/number) | How far away (along the X and Y axes) should this line go? | Yes |
-| [`tag`](/docs/kcl/types/tag) | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
+| `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
 
 ### Returns
 
@@ -36,9 +36,9 @@ bezierCurve(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [0, 10])
   |> bezierCurve(control1 = [5, 0], control2 = [5, 10], end = [10, 10])
   |> line(endAbsolute = [10, 0])

docs/kcl/circleThreePoint.md

@@ -8,14 +8,14 @@ Construct a circle derived from 3 points.
 
 
 
-```js
+```kcl
 circleThreePoint(
-  sketchSurfaceOrGroup: SketchOrSurface,
-  p1: [number],
-  p2: [number],
-  p3: [number],
-  tag?: TagDeclarator,
-): Sketch
+  sketchSurfaceOrGroup: [[Sketch](/docs/kcl/types/Sketch)OrSurface](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch)OrSurface),
+  p1: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  p2: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  p3: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  tag?: [TagDeclarator](/docs/kcl/types#tag-declaration),
+): [Sketch](/docs/kcl/types/Sketch)
 ```
 
 
@@ -27,7 +27,7 @@ circleThreePoint(
 | `p1` | [`[number]`](/docs/kcl/types/number) | 1st point to derive the circle. | Yes |
 | `p2` | [`[number]`](/docs/kcl/types/number) | 2nd point to derive the circle. | Yes |
 | `p3` | [`[number]`](/docs/kcl/types/number) | 3rd point to derive the circle. | Yes |
-| [`tag`](/docs/kcl/types/tag) | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Identifier for the circle to reference elsewhere. | No |
+| `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Identifier for the circle to reference elsewhere. | No |
 
 ### Returns
 
@@ -36,7 +36,7 @@ circleThreePoint(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XY)
   |> circleThreePoint(p1 = [10, 10], p2 = [20, 8], p3 = [15, 5])
   |> extrude(length = 5)

docs/kcl/consts/std-END.md

@@ -8,7 +8,7 @@ Identifies the ending face of an extrusion. I.e., the new face created by an ext
 
 
 
-```js
+```kcl
 std::END: string = 'end'
 ```
 

docs/kcl/consts/std-START.md

@@ -8,7 +8,7 @@ Identifies the starting face of an extrusion. I.e., the face which is extruded.
 
 
 
-```js
+```kcl
 std::START: string = 'start'
 ```
 

docs/kcl/consts/std-X.md

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::X
 ```
 

docs/kcl/consts/std-XY.md

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::XY
 ```
 

docs/kcl/consts/std-XZ.md

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::XZ
 ```
 

docs/kcl/consts/std-Y.md

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::Y
 ```
 

docs/kcl/consts/std-YZ.md

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::YZ
 ```
 

docs/kcl/consts/std-Z.md

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::Z
 ```
 

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

@@ -8,15 +8,15 @@ The value of Euler’s number `e`.
 
 
 
-```js
+```kcl
 std::math::E: number = 2.71828182845904523536028747135266250_
 ```
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 30,
     length = 2 * E ^ 2,

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

@@ -8,17 +8,17 @@ The value of `pi`, Archimedes’ constant (π).
 
 
 
-```js
-std::math::PI: number = 3.14159265358979323846264338327950288_
+```kcl
+std::math::PI: number(_?) = 3.14159265358979323846264338327950288_?
 ```
 
 ### Examples
 
-```js
+```kcl
 circumference = 70
 
 exampleSketch = startSketchOn(XZ)
- |> circle(center = [0, 0], radius = circumference / (2 * PI))
+ |> circle(center = [0, 0], radius = (circumference / (2 * PI)): number(mm))
 
 example = extrude(exampleSketch, length = 5)
 ```

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

@@ -8,15 +8,15 @@ The value of `tau`, the full circle constant (τ). Equal to 2π.
 
 
 
-```js
+```kcl
 std::math::TAU: number = 6.28318530717958647692528676655900577_
 ```
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 50,
     length = 10 * TAU,

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

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::turns::HALF_TURN: number(deg) = 180deg
 ```
 

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

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::turns::QUARTER_TURN: number(deg) = 90deg
 ```
 

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

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::turns::THREE_QUARTER_TURN: number(deg) = 270deg
 ```
 

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

@@ -8,7 +8,7 @@ layout: manual
 
 
 
-```js
+```kcl
 std::turns::ZERO: number = 0
 ```
 

docs/kcl/e.md

@@ -29,7 +29,7 @@ e(): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = 30, length = 2 * e() ^ 2)
   |> yLine(endAbsolute = 0)
   |> close()

docs/kcl/getCommonEdge.md

@@ -8,8 +8,8 @@ Get the shared edge between two faces.
 
 
 
-```js
-getCommonEdge(faces: [TagIdentifier]): Uuid
+```kcl
+getCommon[Edge](/docs/kcl/types/Edge)(faces: [[TagIdentifier](/docs/kcl/types#tag-identifier)]): Uuid
 ```
 
 
@@ -26,13 +26,13 @@ getCommonEdge(faces: [TagIdentifier]): Uuid
 
 ### Examples
 
-```js
+```kcl
 // Get an edge shared between two faces, created after a chamfer.
 
 
 scale = 20
 part001 = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [0, scale])
   |> line(end = [scale, 0])
   |> line(end = [0, -scale])

docs/kcl/getNextAdjacentEdge.md

@@ -8,8 +8,8 @@ Get the next adjacent edge to the edge given.
 
 
 
-```js
-getNextAdjacentEdge(tag: TagIdentifier): Uuid
+```kcl
+getNextAdjacent[Edge](/docs/kcl/types/Edge)(edge: [TagIdentifier](/docs/kcl/types#tag-identifier)): Uuid
 ```
 
 
@@ -17,7 +17,7 @@ getNextAdjacentEdge(tag: TagIdentifier): Uuid
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) |  | Yes |
+| `edge` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The tag of the edge you want to find the next adjacent edge of. | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ getNextAdjacentEdge(tag: TagIdentifier): Uuid
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> angledLine(angle = 60, length = 10)
   |> angledLine(angle = 120, length = 10)

docs/kcl/getOppositeEdge.md

@@ -8,8 +8,8 @@ Get the opposite edge to the edge given.
 
 
 
-```js
-getOppositeEdge(tag: TagIdentifier): Uuid
+```kcl
+getOpposite[Edge](/docs/kcl/types/Edge)(edge: [TagIdentifier](/docs/kcl/types#tag-identifier)): Uuid
 ```
 
 
@@ -17,7 +17,7 @@ getOppositeEdge(tag: TagIdentifier): Uuid
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) |  | Yes |
+| `edge` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The tag of the edge you want to find the opposite edge of. | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ getOppositeEdge(tag: TagIdentifier): Uuid
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> angledLine(angle = 60, length = 10)
   |> angledLine(angle = 120, length = 10)

docs/kcl/getPreviousAdjacentEdge.md

@@ -8,8 +8,8 @@ Get the previous adjacent edge to the edge given.
 
 
 
-```js
-getPreviousAdjacentEdge(tag: TagIdentifier): Uuid
+```kcl
+getPreviousAdjacent[Edge](/docs/kcl/types/Edge)(edge: [TagIdentifier](/docs/kcl/types#tag-identifier)): Uuid
 ```
 
 
@@ -17,7 +17,7 @@ getPreviousAdjacentEdge(tag: TagIdentifier): Uuid
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) |  | Yes |
+| `edge` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The tag of the edge you want to find the previous adjacent edge of. | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ getPreviousAdjacentEdge(tag: TagIdentifier): Uuid
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> angledLine(angle = 60, length = 10)
   |> angledLine(angle = 120, length = 10)

docs/kcl/index.md

@@ -30,34 +30,22 @@ layout: manual
   * [`Y`](kcl/consts/std-Y)
   * [`YZ`](kcl/consts/std-YZ)
   * [`Z`](kcl/consts/std-Z)
-  * [`abs`](kcl/abs)
-  * [`acos`](kcl/acos)
-  * [`angleToMatchLengthX`](kcl/angleToMatchLengthX)
-  * [`angleToMatchLengthY`](kcl/angleToMatchLengthY)
   * [`angledLine`](kcl/angledLine)
   * [`angledLineThatIntersects`](kcl/angledLineThatIntersects)
   * [`appearance`](kcl/appearance)
   * [`arc`](kcl/arc)
-  * [`asin`](kcl/asin)
   * [`assert`](kcl/assert)
   * [`assertIs`](kcl/assertIs)
-  * [`atan`](kcl/atan)
-  * [`atan2`](kcl/atan2)
   * [`bezierCurve`](kcl/bezierCurve)
-  * [`ceil`](kcl/ceil)
-  * [`chamfer`](kcl/chamfer)
   * [`circleThreePoint`](kcl/circleThreePoint)
+  * [`clone`](kcl/clone)
   * [`close`](kcl/close)
   * [`extrude`](kcl/extrude)
-  * [`fillet`](kcl/fillet)
-  * [`floor`](kcl/floor)
   * [`getCommonEdge`](kcl/getCommonEdge)
   * [`getNextAdjacentEdge`](kcl/getNextAdjacentEdge)
   * [`getOppositeEdge`](kcl/getOppositeEdge)
   * [`getPreviousAdjacentEdge`](kcl/getPreviousAdjacentEdge)
   * [`helix`](kcl/std-helix)
-  * [`hole`](kcl/hole)
-  * [`hollow`](kcl/hollow)
   * [`intersect`](kcl/intersect)
   * [`involuteCircular`](kcl/involuteCircular)
   * [`lastSegX`](kcl/lastSegX)
@@ -66,15 +54,9 @@ layout: manual
   * [`legAngY`](kcl/legAngY)
   * [`legLen`](kcl/legLen)
   * [`line`](kcl/line)
-  * [`ln`](kcl/ln)
   * [`loft`](kcl/loft)
-  * [`log`](kcl/log)
-  * [`log10`](kcl/log10)
-  * [`log2`](kcl/log2)
   * [`map`](kcl/map)
-  * [`max`](kcl/max)
-  * [`min`](kcl/min)
-  * [`offsetPlane`](kcl/offsetPlane)
+  * [`offsetPlane`](kcl/std-offsetPlane)
   * [`patternCircular2d`](kcl/patternCircular2d)
   * [`patternCircular3d`](kcl/patternCircular3d)
   * [`patternLinear2d`](kcl/patternLinear2d)
@@ -83,16 +65,13 @@ layout: manual
   * [`patternTransform2d`](kcl/patternTransform2d)
   * [`polygon`](kcl/polygon)
   * [`pop`](kcl/pop)
-  * [`pow`](kcl/pow)
   * [`profileStart`](kcl/profileStart)
   * [`profileStartX`](kcl/profileStartX)
   * [`profileStartY`](kcl/profileStartY)
   * [`push`](kcl/push)
   * [`reduce`](kcl/reduce)
-  * [`rem`](kcl/rem)
   * [`revolve`](kcl/std-revolve)
   * [`rotate`](kcl/rotate)
-  * [`round`](kcl/round)
   * [`scale`](kcl/scale)
   * [`segAng`](kcl/segAng)
   * [`segEnd`](kcl/segEnd)
@@ -102,22 +81,13 @@ layout: manual
   * [`segStart`](kcl/segStart)
   * [`segStartX`](kcl/segStartX)
   * [`segStartY`](kcl/segStartY)
-  * [`shell`](kcl/shell)
-  * [`sqrt`](kcl/sqrt)
-  * [`startProfileAt`](kcl/startProfileAt)
+  * [`startProfile`](kcl/startProfile)
   * [`startSketchOn`](kcl/startSketchOn)
   * [`subtract`](kcl/subtract)
+  * [`subtract2d`](kcl/subtract2d)
   * [`sweep`](kcl/sweep)
   * [`tangentToEnd`](kcl/tangentToEnd)
   * [`tangentialArc`](kcl/tangentialArc)
-  * [`toCentimeters`](kcl/std-toCentimeters)
-  * [`toDegrees`](kcl/std-toDegrees)
-  * [`toFeet`](kcl/std-toFeet)
-  * [`toInches`](kcl/std-toInches)
-  * [`toMeters`](kcl/std-toMeters)
-  * [`toMillimeters`](kcl/std-toMillimeters)
-  * [`toRadians`](kcl/std-toRadians)
-  * [`toYards`](kcl/std-toYards)
   * [`translate`](kcl/translate)
   * [`union`](kcl/union)
   * [`xLine`](kcl/xLine)
@@ -126,13 +96,35 @@ layout: manual
   * [`E`](kcl/consts/std-math-E)
   * [`PI`](kcl/consts/std-math-PI)
   * [`TAU`](kcl/consts/std-math-TAU)
+  * [`abs`](kcl/std-math-abs)
+  * [`acos`](kcl/std-math-acos)
+  * [`asin`](kcl/std-math-asin)
+  * [`atan`](kcl/std-math-atan)
+  * [`atan2`](kcl/std-math-atan2)
+  * [`ceil`](kcl/std-math-ceil)
   * [`cos`](kcl/std-math-cos)
+  * [`floor`](kcl/std-math-floor)
+  * [`ln`](kcl/std-math-ln)
+  * [`log`](kcl/std-math-log)
+  * [`log10`](kcl/std-math-log10)
+  * [`log2`](kcl/std-math-log2)
+  * [`max`](kcl/std-math-max)
+  * [`min`](kcl/std-math-min)
   * [`polar`](kcl/std-math-polar)
+  * [`pow`](kcl/std-math-pow)
+  * [`rem`](kcl/std-math-rem)
+  * [`round`](kcl/std-math-round)
   * [`sin`](kcl/std-math-sin)
+  * [`sqrt`](kcl/std-math-sqrt)
   * [`tan`](kcl/std-math-tan)
 * **std::sketch**
   * [`circle`](kcl/std-sketch-circle)
   * [`mirror2d`](kcl/std-sketch-mirror2d)
+* **std::solid**
+  * [`chamfer`](kcl/std-solid-chamfer)
+  * [`fillet`](kcl/std-solid-fillet)
+  * [`hollow`](kcl/std-solid-hollow)
+  * [`shell`](kcl/std-solid-shell)
 * **std::turns**
   * [`turns::HALF_TURN`](kcl/consts/std-turns-HALF_TURN)
   * [`turns::QUARTER_TURN`](kcl/consts/std-turns-QUARTER_TURN)
@@ -149,3 +141,12 @@ layout: manual
   * [`Point3d`](kcl/types/Point3d)
   * [`Sketch`](kcl/types/Sketch)
   * [`Solid`](kcl/types/Solid)
+* **std::units**
+  * [`units::toCentimeters`](kcl/std-units-toCentimeters)
+  * [`units::toDegrees`](kcl/std-units-toDegrees)
+  * [`units::toFeet`](kcl/std-units-toFeet)
+  * [`units::toInches`](kcl/std-units-toInches)
+  * [`units::toMeters`](kcl/std-units-toMeters)
+  * [`units::toMillimeters`](kcl/std-units-toMillimeters)
+  * [`units::toRadians`](kcl/std-units-toRadians)
+  * [`units::toYards`](kcl/std-units-toYards)

docs/kcl/involuteCircular.md

@@ -8,15 +8,15 @@ Extend the current sketch with a new involute circular curve.
 
 
 
-```js
+```kcl
 involuteCircular(
-  sketch: Sketch,
-  startRadius: number,
-  endRadius: number,
-  angle: number,
-  reverse?: bool,
-  tag?: TagDeclarator,
-): Sketch
+  sketch: [Sketch](/docs/kcl/types/Sketch),
+  startRadius: [number](/docs/kcl/types/number),
+  endRadius: [number](/docs/kcl/types/number),
+  angle: [number](/docs/kcl/types/number),
+  reverse?: [bool](/docs/kcl/types/bool),
+  tag?: [TagDeclarator](/docs/kcl/types#tag-declaration),
+): [Sketch](/docs/kcl/types/Sketch)
 ```
 
 
@@ -29,7 +29,7 @@ involuteCircular(
 | `endRadius` | [`number`](/docs/kcl/types/number) | The involute is described between two circles, end_radius is the radius of the outer circle. | Yes |
 | `angle` | [`number`](/docs/kcl/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/types/bool) | If reverse is true, the segment will start from the end of the involute, otherwise it will start from that start. Defaults to false. | No |
-| [`tag`](/docs/kcl/types/tag) | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
+| `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
 
 ### Returns
 
@@ -38,11 +38,11 @@ involuteCircular(
 
 ### Examples
 
-```js
+```kcl
 a = 10
 b = 14
 startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> involuteCircular(startRadius = a, endRadius = b, angle = 60)
   |> involuteCircular(
        startRadius = a,

docs/kcl/known-issues.md

@@ -22,6 +22,5 @@ once fixed in engine will just start working here with no language changes.
     chamfer cases work currently.
 
 - **Appearance**: Changing the appearance on a loft does not work. 
-    Changing the appearance on an imported model does not work.
 
 - **CSG Booleans**: Coplanar (bodies that share a plane) unions, subtractions, and intersections are not currently supported.

docs/kcl/lastSegX.md

@@ -8,8 +8,8 @@ Extract the 'x' axis value of the last line segment in the provided 2-d sketch.
 
 
 
-```js
-lastSegX(sketch: Sketch): number
+```kcl
+lastSegX(sketch: [Sketch](/docs/kcl/types/Sketch)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -26,9 +26,9 @@ lastSegX(sketch: Sketch): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [5, 0])
   |> line(end = [20, 5])
   |> line(end = [lastSegX(%), 0])

docs/kcl/lastSegY.md

@@ -8,8 +8,8 @@ Extract the 'y' axis value of the last line segment in the provided 2-d sketch.
 
 
 
-```js
-lastSegY(sketch: Sketch): number
+```kcl
+lastSegY(sketch: [Sketch](/docs/kcl/types/Sketch)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -26,9 +26,9 @@ lastSegY(sketch: Sketch): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [5, 0])
   |> line(end = [20, 5])
   |> line(end = [0, lastSegY(%)])

docs/kcl/legAngX.md

@@ -8,11 +8,11 @@ Compute the angle of the given leg for x.
 
 
 
-```js
+```kcl
 legAngX(
-  hypotenuse: number,
-  leg: number,
-): number
+  hypotenuse: [number](/docs/kcl/types/number),
+  leg: [number](/docs/kcl/types/number),
+): [number](/docs/kcl/types/number)
 ```
 
 ### Tags
@@ -24,8 +24,8 @@ legAngX(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `hypotenuse` | [`number`](/docs/kcl/types/number) |  | Yes |
-| `leg` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `hypotenuse` | [`number`](/docs/kcl/types/number) | The length of the triangle's hypotenuse | Yes |
+| `leg` | [`number`](/docs/kcl/types/number) | The length of one of the triangle's legs (i.e. non-hypotenuse side) | Yes |
 
 ### Returns
 
@@ -34,8 +34,8 @@ legAngX(
 
 ### Examples
 
-```js
-legAngX(5, 3)
+```kcl
+legAngX(hypotenuse = 5, leg = 3)
 ```
 
 

docs/kcl/legAngY.md

@@ -8,11 +8,11 @@ Compute the angle of the given leg for y.
 
 
 
-```js
+```kcl
 legAngY(
-  hypotenuse: number,
-  leg: number,
-): number
+  hypotenuse: [number](/docs/kcl/types/number),
+  leg: [number](/docs/kcl/types/number),
+): [number](/docs/kcl/types/number)
 ```
 
 ### Tags
@@ -24,8 +24,8 @@ legAngY(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `hypotenuse` | [`number`](/docs/kcl/types/number) |  | Yes |
-| `leg` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `hypotenuse` | [`number`](/docs/kcl/types/number) | The length of the triangle's hypotenuse | Yes |
+| `leg` | [`number`](/docs/kcl/types/number) | The length of one of the triangle's legs (i.e. non-hypotenuse side) | Yes |
 
 ### Returns
 
@@ -34,8 +34,8 @@ legAngY(
 
 ### Examples
 
-```js
-legAngY(5, 3)
+```kcl
+legAngY(hypotenuse = 5, leg = 3)
 ```
 
 

docs/kcl/legLen.md

@@ -8,11 +8,11 @@ Compute the length of the given leg.
 
 
 
-```js
+```kcl
 legLen(
-  hypotenuse: number,
-  leg: number,
-): number
+  hypotenuse: [number](/docs/kcl/types/number),
+  leg: [number](/docs/kcl/types/number),
+): [number](/docs/kcl/types/number)
 ```
 
 ### Tags
@@ -24,8 +24,8 @@ legLen(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `hypotenuse` | [`number`](/docs/kcl/types/number) |  | Yes |
-| `leg` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `hypotenuse` | [`number`](/docs/kcl/types/number) | The length of the triangle's hypotenuse | Yes |
+| `leg` | [`number`](/docs/kcl/types/number) | The length of one of the triangle's legs (i.e. non-hypotenuse side) | Yes |
 
 ### Returns
 
@@ -34,8 +34,8 @@ legLen(
 
 ### Examples
 
-```js
-legLen(5, 3)
+```kcl
+legLen(hypotenuse = 5, leg = 3)
 ```
 
 

docs/kcl/line.md

@@ -8,13 +8,13 @@ Extend the current sketch with a new straight line.
 
 
 
-```js
+```kcl
 line(
-  sketch: Sketch,
-  endAbsolute?: [number],
-  end?: [number],
-  tag?: TagDeclarator,
-): Sketch
+  sketch: [Sketch](/docs/kcl/types/Sketch),
+  endAbsolute?: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  end?: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  tag?: [TagDeclarator](/docs/kcl/types#tag-declaration),
+): [Sketch](/docs/kcl/types/Sketch)
 ```
 
 
@@ -25,7 +25,7 @@ line(
 | `sketch` | [`Sketch`](/docs/kcl/types/Sketch) | Which sketch should this path be added to? | Yes |
 | `endAbsolute` | [`[number]`](/docs/kcl/types/number) | Which absolute point should this line go to? Incompatible with `end`. | No |
 | `end` | [`[number]`](/docs/kcl/types/number) | How far away (along the X and Y axes) should this line go? Incompatible with `endAbsolute`. | No |
-| [`tag`](/docs/kcl/types/tag) | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
+| `tag` | [`TagDeclarator`](/docs/kcl/types#tag-declaration) | Create a new tag which refers to this line | No |
 
 ### Returns
 
@@ -34,9 +34,9 @@ line(
 
 ### Examples
 
-```js
+```kcl
 triangle = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   // The END argument means it ends at exactly [10, 0].
   // This is an absolute measurement, it is NOT relative to
   // the start of the sketch.
@@ -47,7 +47,7 @@ triangle = startSketchOn(XZ)
   |> extrude(length = 5)
 
 box = startSketchOn(XZ)
-  |> startProfileAt([10, 10], %)
+  |> startProfile(at = [10, 10])
   // The 'to' argument means move the pen this much.
   // So, [10, 0] is a relative distance away from the current point.
   |> line(end = [10, 0])

docs/kcl/modules.md

@@ -10,7 +10,7 @@ isolated from other files as a separate module.
 When you define a function, you can use `export` before it to make it available
 to other modules.
 
-```
+```kcl
 // util.kcl
 export fn increment(x) {
   return x + 1
@@ -31,11 +31,11 @@ Imported files _must_ be in the same project so that units are uniform across
 modules. This means that it must be in the same directory.
 
 Import statements must be at the top-level of a file. It is not allowed to have
-an `import` statement inside a function or in the body of an if-else.
+an `import` statement inside a function or in the body of an if‑else.
 
 Multiple functions can be exported in a file.
 
-```
+```kcl
 // util.kcl
 export fn increment(x) {
   return x + 1
@@ -58,6 +58,215 @@ Imported symbols can be renamed for convenience or to avoid name collisions.
 import increment as inc, decrement as dec from "util.kcl"
 ```
 
+---
+
+## Functions vs `clone`
+
+There are two common patterns for re‑using geometry:
+
+1. **Wrap the construction in a function** – flexible and fully parametric.
+2. **Duplicate an existing object with `clone`** – lightning‑fast, but an exact
+   duplicate.
+
+### Parametric function example
+
+```kcl
+fn cube(center) {
+  return startSketchOn(XY)
+    |> startProfile(at = [center[0] - 10, center[1] - 10])
+    |> line(endAbsolute = [center[0] + 10, center[1] - 10])
+    |> line(endAbsolute = [center[0] + 10, center[1] + 10])
+    |> line(endAbsolute = [center[0] - 10, center[1] + 10])
+    |> close()
+    |> extrude(length = 10)
+}
+
+myCube = cube([0, 0])
+```
+
+*Pros*
+- Any argument can be a parameter – size, position, appearance, etc.
+- Works great inside loops, arrays, or optimisation sweeps.
+
+*Cons*
+- Every invocation rebuilds the entire feature tree.
+- **Slower** than a straight duplicate – each call is its own render job.
+
+### `clone` example
+
+```kcl
+sketch001 = startSketchOn(-XZ)
+  |> circle(center = [0, 0], radius = 10)
+  |> extrude(length = 5) 
+  |> appearance(color = "#ff0000", metalness = 90, roughness = 90)
+
+sketch002 = clone(sketch001)  // ✓ instant copy
+```
+
+*Pros*
+- Roughly an O(1) operation – we just duplicate the underlying engine handle.
+- Perfect when you need ten identical bolts or two copies of the same imported STEP file.
+
+*Cons*
+- **Not parametric** – the clone is exactly the same shape as the source.
+- If you need to tweak dimensions per‑instance, you’re back to a function.
+
+> **Rule of thumb** – Reach for `clone` when the geometry is already what you want. Reach for a function when you need customisation.
+
+---
+
+## Module‑level parallelism
+
+Under the hood, the Design Studio runs **every module in parallel** where it can. This means:
+
+- The top‑level code of `foo.kcl`, `bar.kcl`, and `baz.kcl` all start executing immediately and concurrently.
+- Imports that read foreign files (STEP/OBJ/…) overlap their I/O and background render.
+- CPU‑bound calculations in separate modules get their own worker threads.
+
+### Why modules beat one‑big‑file
+
+If you shoe‑horn everything into `main.kcl`, each statement runs sequentially:
+
+```norun
+import "big.step" as gizmo  // blocks main while reading
+
+gizmo |> translate(x=50)    // blocks again while waiting for render
+```
+
+Split `gizmo` into its own file and the read/render can overlap whatever else `main.kcl` is doing.
+
+```norun
+// gizmo.kcl                   (worker A)
+import "big.step"
+
+// main.kcl                    (worker B)
+import "gizmo.kcl" as gizmo   // non‑blocking
+
+// ... other setup ...
+
+gizmo |> translate(x=50)      // only blocks here
+```
+
+### Gotcha: defining but **not** calling functions
+
+Defining a function inside a module is instantaneous – we just record the byte‑code. The heavy lifting happens when the function is **called**. So:
+
+```norun
+// util.kcl
+export fn makeBolt(size) { /* … expensive CAD … */ }
+```
+
+If `main.kcl` waits until the very end to call `makeBolt`, *none* of that work was parallelised – you’ve pushed the cost back onto the serial tail of your script.
+
+**Better:** call it early or move the invocation into another module.
+
+```norun
+// bolt_instance.kcl
+import makeBolt from "util.kcl"
+bolt = makeBolt(5)  // executed in parallel
+bolt
+```
+
+Now `main.kcl` can `import "bolt_instance.kcl" as bolt` and get the result that was rendered while it was busy doing other things.
+
+---
+
+## Whole module import
+
+You can also import the whole module. This is useful if you want to use the
+result of a module as a variable, like a part.
+
+```norun
+import "tests/inputs/cube.kcl" as cube
+cube
+  |> translate(x=10)
+```
+
+This imports the whole module and makes it available as `cube`. You can then
+use it like any other object. The `cube` variable is now a reference to the
+result of the module. This means that if you change the module, the `cube`
+variable will change as well.
+
+In `cube.kcl`, you cannot have multiple objects. It has to be a single part. If
+you have multiple objects, you will get an error. This is because the module is
+expected to return a single object that can be used as a variable.
+
+The last expression or variable definition becomes the module's return value.
+The module is expected to return a single object that can be used as a variable
+by whatever imports it.
+
+So for example, this is allowed:
+
+```norun
+... a bunch of code to create cube and cube2 ...
+
+myUnion = union([cube, cube2])
+```
+
+You can also do this:
+
+```norun
+... a bunch of code to create cube and cube2 ...
+
+union([cube, cube2])
+```
+
+Either way, the last line will return the union of the two objects.
+
+Or what you could do instead is:
+
+```norun
+... a bunch of code to create cube and cube2 ...
+
+myUnion = union([cube, cube2])
+myUnion
+```
+
+This will assign the union of the two objects to a variable, and then return it
+on the last statement. It's simply another way of doing the same thing.
+
+The final statement is what's important because it's the return value of the
+entire module. The module is expected to return a single object that can be used
+as a variable by the file that imports it.
+
+---
+
+## Multiple instances of the same import
+
+Whether you are importing a file from another CAD system or a KCL file, that
+file represents object(s) in memory. If you import the same file multiple times,
+it will only be rendered once.
+
+If you want to have multiple instances of the same object, you can use the
+[`clone`](/docs/kcl/clone) function. This will render a new instance of the object in memory.
+
+```norun
+import cube from "tests/inputs/cube.kcl"
+
+cube  
+  |> translate(x=10)
+clone(cube)
+  |> translate(x=20)
+```
+
+In the sample above, the `cube` object is imported from a KCL file. The first
+instance is translated 10 units in the x direction. The second instance is
+cloned and translated 20 units in the x direction. The two instances are now
+separate objects in memory, and can be manipulated independently.
+
+Here is an example with a file from another CAD system:
+
+```kcl
+import "tests/inputs/cube.step" as cube
+
+cube
+  |> translate(x=10)
+clone(cube)
+  |> translate(x=20)
+```
+
+---
+
 ## Importing files from other CAD systems
 
 `import` can also be used to import files from other CAD systems. The format of the statement is the
@@ -69,26 +278,18 @@ import "tests/inputs/cube.obj"
 // Use `cube` just like a KCL object.
 ```
 
-```norun
-import "tests/inputs/cube-2.sldprt" as cube
+```kcl
+import "tests/inputs/cube.sldprt" as cube
 
 // Use `cube` just like a KCL object.
 ```
 
-You can make the file format explicit using a format attribute (useful if using a different
-extension), e.g.,
-
-```norun
-@(format = obj)
-import "tests/inputs/cube"
-```
-
 For formats lacking unit data (such as STL, OBJ, or PLY files), the default
 unit of measurement is millimeters. Alternatively you may specify the unit
-by using an attirbute. Likewise, you can also specify a coordinate system. E.g.,
+by using an attribute. Likewise, you can also specify a coordinate system. E.g.,
 
-```norun
-@(unitLength = ft, coords = opengl)
+```kcl
+@(lengthUnit = ft, coords = opengl)
 import "tests/inputs/cube.obj"
 ```
 
@@ -110,97 +311,55 @@ Coordinate systems:
 - `opengl`, forward: +Z, up: +Y, handedness: right
 - `vulkan`, forward: +Z, up: -Y, handedness: left
 
-### Performance
+---
 
-Parallelized foreign-file imports now let you overlap file reads, initialization,
+## Performance deep‑dive for foreign‑file imports
+
+Parallelized foreign‑file imports now let you overlap file reads, initialization,
 and rendering. To maximize throughput, you need to understand the three distinct
 stages—reading, initializing (background render start), and invocation (blocking)
 —and structure your code to defer blocking operations until the end.
 
-#### Foreign Import Execution Stages
+### Foreign import execution stages
 
-1. **Import (Read) Stage**  
-   ```norun
+1. **Import (Read / Initialization) Stage**
+   ```kcl
    import "tests/inputs/cube.step" as cube
-   ```  
-   - Reads the file from disk and makes its API available.  
-   - **Does _not_** start Engine rendering or block your script.
+   ```
+   - Reads the file from disk and makes its API available.
+   - Starts engine rendering but **does not block** your script.
+   - This kick‑starts the render pipeline while you keep executing other code.
 
-2. **Initialization (Background Render) Stage**  
-   ```norun
+2. **Invocation (Blocking) Stage**
+   ```kcl
    import "tests/inputs/cube.step" as cube
 
-   myCube = cube    // <- This line starts background rendering
-   ```  
-   - Invoking the imported symbol (assignment or plain call) triggers Engine rendering _in the background_.  
-   - This kick‑starts the render pipeline but doesn’t block—you can continue other work while the Engine processes the model.
+   cube
+     |> translate(z=10) // ← blocks here only
+   ```
+   - Any method call (e.g., `translate`, `scale`, `rotate`) waits for the background render to finish before applying transformations.
 
-3. **Invocation (Blocking) Stage**  
-   ```norun
-   import "tests/inputs/cube.step" as cube
+### Best practices
 
-   myCube = cube
+#### 1. Defer blocking calls
 
-   myCube
-    |> translate(z=10) // <- This line blocks
-   ```  
-   - Any method call (e.g., `translate`, `scale`, `rotate`) waits for the background render to finish before applying transformations.  
-   - This is the only point where your script will block.
-
-> **Nuance:**  Foreign imports differ from pure KCL modules—calling the same import symbol multiple times (e.g., `screw` twice) starts background rendering twice.
-
-#### Best Practices
-
-##### 1. Defer Blocking Calls
-Initialize early but delay all transformations until after your heavy computation:
-```norun
-import "tests/inputs/cube.step" as cube     // 1) Read
-
-myCube = cube                               // 2) Background render starts
+```kcl
+import "tests/inputs/cube.step" as cube     // 1) Read / Background render starts
 
 
-// --- perform other operations and calculations or setup here ---
+// --- perform other operations and calculations here ---
 
 
-myCube
-  |> translate(z=10)                        // 3) Blocks only here
-```
-
-##### 2. Encapsulate Imports in Modules
-Keep `main.kcl` free of reads and initialization; wrap them:
-
-```norun
-// imports.kcl
-import "tests/inputs/cube.step" as cube    // Read only
-
-
-export myCube = cube                      // Kick off rendering
-```
-
-```norun
-// main.kcl
-import myCube from "imports.kcl"  // Import the initialized object 
-
-
-// ... computations ...
-
-
-myCube
-  |> translate(z=10)              // Blocking call at the end
-```
-
-##### 3. Avoid Immediate Method Calls
-
-```norun
-import "tests/inputs/cube.step" as cube
-
 cube
-  |> translate(z=10)              // Blocks immediately, negating parallelism
+  |> translate(z=10)                        // 2) Blocks only here
 ```
 
-Both calling methods right on `cube` immediately or leaving an implicit import without assignment introduce blocking.
+#### 2. Split heavy work into separate modules
 
-#### Future Improvements
+Place computationally expensive or IO‑heavy work into its own module so it can render in parallel while `main.kcl` continues.
+
+#### Future improvements
+
+Upcoming releases will auto‑analyse dependencies and only block when truly necessary. Until then, explicit deferral will give you the best performance.
 
-Upcoming releases will auto‑analyze dependencies and only block when truly necessary. Until then, explicit deferral and modular wrapping give you the best performance.
 

docs/kcl/patternCircular2d.md

@@ -8,15 +8,15 @@ Repeat a 2-dimensional sketch some number of times along a partial or complete c
 
 
 
-```js
+```kcl
 patternCircular2d(
-  sketchSet: [Sketch],
+  sketchSet: [[[Sketch](/docs/kcl/types/Sketch)]](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch)),
   instances: integer,
-  center: [number],
-  arcDegrees: number,
-  rotateDuplicates: bool,
-  useOriginal?: bool,
-): [Sketch]
+  center: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  arcDegrees: [number](/docs/kcl/types/number),
+  rotateDuplicates: [bool](/docs/kcl/types/bool),
+  useOriginal?: [bool](/docs/kcl/types/bool),
+): [[[Sketch](/docs/kcl/types/Sketch)]](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch))
 ```
 
 
@@ -38,9 +38,9 @@ patternCircular2d(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([.5, 25], %)
+  |> startProfile(at = [.5, 25])
   |> line(end = [0, 5])
   |> line(end = [-1, 0])
   |> line(end = [0, -5])

docs/kcl/patternCircular3d.md

@@ -8,16 +8,16 @@ Repeat a 3-dimensional solid some number of times along a partial or complete ci
 
 
 
-```js
+```kcl
 patternCircular3d(
-  solids: [Solid],
+  solids: [[[Solid](/docs/kcl/types/Solid)]](/docs/kcl/types/[Solid](/docs/kcl/types/Solid)),
   instances: integer,
-  axis: [number],
-  center: [number],
-  arcDegrees: number,
-  rotateDuplicates: bool,
-  useOriginal?: bool,
-): [Solid]
+  axis: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  center: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  arcDegrees: [number](/docs/kcl/types/number),
+  rotateDuplicates: [bool](/docs/kcl/types/bool),
+  useOriginal?: [bool](/docs/kcl/types/bool),
+): [[[Solid](/docs/kcl/types/Solid)]](/docs/kcl/types/[Solid](/docs/kcl/types/Solid))
 ```
 
 
@@ -40,7 +40,7 @@ patternCircular3d(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
   |> circle(center = [0, 0], radius = 1)
 

docs/kcl/patternLinear2d.md

@@ -8,14 +8,14 @@ Repeat a 2-dimensional sketch along some dimension, with a dynamic amount of dis
 
 
 
-```js
+```kcl
 patternLinear2d(
-  sketches: [Sketch],
+  sketches: [[[Sketch](/docs/kcl/types/Sketch)]](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch)),
   instances: integer,
-  distance: number,
-  axis: [number],
-  useOriginal?: bool,
-): [Sketch]
+  distance: [number](/docs/kcl/types/number),
+  axis: [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number)),
+  useOriginal?: [bool](/docs/kcl/types/bool),
+): [[[Sketch](/docs/kcl/types/Sketch)]](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch))
 ```
 
 
@@ -36,7 +36,7 @@ patternLinear2d(
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
   |> circle(center = [0, 0], radius = 1)
   |> patternLinear2d(axis = [1, 0], instances = 7, distance = 4)

docs/kcl/patternTransform2d.md

@@ -8,13 +8,13 @@ Just like patternTransform, but works on 2D sketches not 3D solids.
 
 
 
-```js
+```kcl
 patternTransform2d(
-  sketches: [Sketch],
+  sketches: [[[Sketch](/docs/kcl/types/Sketch)]](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch)),
   instances: integer,
   transform: FunctionSource,
-  useOriginal?: bool,
-): [Sketch]
+  useOriginal?: [bool](/docs/kcl/types/bool),
+): [[[Sketch](/docs/kcl/types/Sketch)]](/docs/kcl/types/[Sketch](/docs/kcl/types/Sketch))
 ```
 
 
@@ -34,7 +34,7 @@ patternTransform2d(
 
 ### Examples
 
-```js
+```kcl
 // Each instance will be shifted along the X axis.
 fn transform(id) {
   return { translate = [4 * id, 0] }

docs/kcl/pop.md

@@ -8,8 +8,8 @@ Remove the last element from an array.
 
 Returns a new array with the last element removed.
 
-```js
-pop(array: [KclValue]): KclValue
+```kcl
+pop(array: [[[KclValue](/docs/kcl/types/KclValue)]](/docs/kcl/types/[KclValue](/docs/kcl/types/KclValue))): [KclValue](/docs/kcl/types/KclValue)
 ```
 
 
@@ -17,7 +17,7 @@ pop(array: [KclValue]): KclValue
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `array` | [`[KclValue]`](/docs/kcl/types/KclValue) | The array to pop from.  Must not be empty. | Yes |
+| `array` | [`[KclValue]`](/docs/kcl/types/KclValue) | The array to pop from. Must not be empty. | Yes |
 
 ### Returns
 
@@ -26,7 +26,7 @@ pop(array: [KclValue]): KclValue
 
 ### Examples
 
-```js
+```kcl
 arr = [1, 2, 3, 4]
 new_arr = pop(arr)
 assert(

docs/kcl/profileStart.md

@@ -8,8 +8,8 @@ Extract the provided 2-dimensional sketch's profile's origin value.
 
 
 
-```js
-profileStart(profile: Sketch): [number]
+```kcl
+profileStart(profile: [Sketch](/docs/kcl/types/Sketch)): [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number))
 ```
 
 
@@ -26,9 +26,9 @@ profileStart(profile: Sketch): [number]
 
 ### Examples
 
-```js
+```kcl
 sketch001 = startSketchOn(XY)
-  |> startProfileAt([5, 2], %)
+  |> startProfile(at = [5, 2])
   |> angledLine(angle = 120, length = 50, tag = $seg01)
   |> angledLine(angle = segAng(seg01) + 120, length = 50)
   |> line(end = profileStart(%))

docs/kcl/profileStartX.md

@@ -8,8 +8,8 @@ Extract the provided 2-dimensional sketch's profile's origin's 'x' value.
 
 
 
-```js
-profileStartX(profile: Sketch): number
+```kcl
+profileStartX(profile: [Sketch](/docs/kcl/types/Sketch)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -26,9 +26,9 @@ profileStartX(profile: Sketch): number
 
 ### Examples
 
-```js
+```kcl
 sketch001 = startSketchOn(XY)
-  |> startProfileAt([5, 2], %)
+  |> startProfile(at = [5, 2])
   |> angledLine(angle = -26.6, length = 50)
   |> angledLine(angle = 90, length = 50)
   |> angledLine(angle = 30, endAbsoluteX = profileStartX(%))

docs/kcl/profileStartY.md

@@ -8,8 +8,8 @@ Extract the provided 2-dimensional sketch's profile's origin's 'y' value.
 
 
 
-```js
-profileStartY(profile: Sketch): number
+```kcl
+profileStartY(profile: [Sketch](/docs/kcl/types/Sketch)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -26,9 +26,9 @@ profileStartY(profile: Sketch): number
 
 ### Examples
 
-```js
+```kcl
 sketch001 = startSketchOn(XY)
-  |> startProfileAt([5, 2], %)
+  |> startProfile(at = [5, 2])
   |> angledLine(angle = -60, length = 14)
   |> angledLine(angle = 30, endAbsoluteY = profileStartY(%))
 ```

docs/kcl/push.md

@@ -8,11 +8,11 @@ Append an element to the end of an array.
 
 Returns a new array with the element appended.
 
-```js
+```kcl
 push(
-  array: [KclValue],
-  elem: KclValue,
-): KclValue
+  array: [[[KclValue](/docs/kcl/types/KclValue)]](/docs/kcl/types/[KclValue](/docs/kcl/types/KclValue)),
+  item: [KclValue](/docs/kcl/types/KclValue),
+): [KclValue](/docs/kcl/types/KclValue)
 ```
 
 
@@ -20,8 +20,8 @@ push(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `array` | [`[KclValue]`](/docs/kcl/types/KclValue) |  | Yes |
-| `elem` | [`KclValue`](/docs/kcl/types/KclValue) | Any KCL value. | Yes |
+| `array` | [`[KclValue]`](/docs/kcl/types/KclValue) | The array which you're adding a new item to. | Yes |
+| `item` | [`KclValue`](/docs/kcl/types/KclValue) | The new item to add to the array | Yes |
 
 ### Returns
 
@@ -30,9 +30,9 @@ push(
 
 ### Examples
 
-```js
+```kcl
 arr = [1, 2, 3]
-new_arr = push(arr, 4)
+new_arr = push(arr, item = 4)
 assert(
   new_arr[3],
   isEqualTo = 4,

docs/kcl/segAng.md

@@ -8,8 +8,8 @@ Compute the angle (in degrees) of the provided line segment.
 
 
 
-```js
-segAng(tag: TagIdentifier): number
+```kcl
+segAng(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -17,7 +17,7 @@ segAng(tag: TagIdentifier): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ segAng(tag: TagIdentifier): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> line(end = [5, 10], tag = $seg01)
   |> line(end = [-10, 0])

docs/kcl/segEnd.md

@@ -8,8 +8,8 @@ Compute the ending point of the provided line segment.
 
 
 
-```js
-segEnd(tag: TagIdentifier): [number]
+```kcl
+segEnd(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number))
 ```
 
 
@@ -17,7 +17,7 @@ segEnd(tag: TagIdentifier): [number]
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,10 +26,10 @@ segEnd(tag: TagIdentifier): [number]
 
 ### Examples
 
-```js
+```kcl
 w = 15
 cube = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [w, 0], tag = $line1)
   |> line(end = [0, w], tag = $line2)
   |> line(end = [-w, 0], tag = $line3)
@@ -39,7 +39,7 @@ cube = startSketchOn(XY)
 
 fn cylinder(radius, tag) {
   return startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> circle(radius = radius, center = segEnd(tag))
     |> extrude(length = radius)
 }

docs/kcl/segEndX.md

@@ -8,8 +8,8 @@ Compute the ending point of the provided line segment along the 'x' axis.
 
 
 
-```js
-segEndX(tag: TagIdentifier): number
+```kcl
+segEndX(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -17,7 +17,7 @@ segEndX(tag: TagIdentifier): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ segEndX(tag: TagIdentifier): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [20, 0], tag = $thing)
   |> line(end = [0, 5])
   |> line(end = [segEndX(thing), 0])

docs/kcl/segEndY.md

@@ -8,8 +8,8 @@ Compute the ending point of the provided line segment along the 'y' axis.
 
 
 
-```js
-segEndY(tag: TagIdentifier): number
+```kcl
+segEndY(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -17,7 +17,7 @@ segEndY(tag: TagIdentifier): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ segEndY(tag: TagIdentifier): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [20, 0])
   |> line(end = [0, 3], tag = $thing)
   |> line(end = [-10, 0])

docs/kcl/segLen.md

@@ -8,8 +8,8 @@ Compute the length of the provided line segment.
 
 
 
-```js
-segLen(tag: TagIdentifier): number
+```kcl
+segLen(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -17,7 +17,7 @@ segLen(tag: TagIdentifier): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ segLen(tag: TagIdentifier): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = 60, length = 10, tag = $thing)
   |> tangentialArc(angle = -120, radius = 5)
   |> angledLine(angle = -60, length = segLen(thing))

docs/kcl/segStart.md

@@ -8,8 +8,8 @@ Compute the starting point of the provided line segment.
 
 
 
-```js
-segStart(tag: TagIdentifier): [number]
+```kcl
+segStart(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [[[number](/docs/kcl/types/number)]](/docs/kcl/types/[number](/docs/kcl/types/number))
 ```
 
 
@@ -17,7 +17,7 @@ segStart(tag: TagIdentifier): [number]
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,10 +26,10 @@ segStart(tag: TagIdentifier): [number]
 
 ### Examples
 
-```js
+```kcl
 w = 15
 cube = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [w, 0], tag = $line1)
   |> line(end = [0, w], tag = $line2)
   |> line(end = [-w, 0], tag = $line3)
@@ -39,7 +39,7 @@ cube = startSketchOn(XY)
 
 fn cylinder(radius, tag) {
   return startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> circle(radius = radius, center = segStart(tag))
     |> extrude(length = radius)
 }

docs/kcl/segStartX.md

@@ -8,8 +8,8 @@ Compute the starting point of the provided line segment along the 'x' axis.
 
 
 
-```js
-segStartX(tag: TagIdentifier): number
+```kcl
+segStartX(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -17,7 +17,7 @@ segStartX(tag: TagIdentifier): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ segStartX(tag: TagIdentifier): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [20, 0], tag = $thing)
   |> line(end = [0, 5])
   |> line(end = [20 - segStartX(thing), 0])

docs/kcl/segStartY.md

@@ -8,8 +8,8 @@ Compute the starting point of the provided line segment along the 'y' axis.
 
 
 
-```js
-segStartY(tag: TagIdentifier): number
+```kcl
+segStartY(tag: [TagIdentifier](/docs/kcl/types#tag-identifier)): [number](/docs/kcl/types/number)
 ```
 
 
@@ -17,7 +17,7 @@ segStartY(tag: TagIdentifier): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| [`tag`](/docs/kcl/types/tag) | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
+| `tag` | [`TagIdentifier`](/docs/kcl/types#tag-identifier) | The line segment being queried by its tag | Yes |
 
 ### Returns
 
@@ -26,9 +26,9 @@ segStartY(tag: TagIdentifier): number
 
 ### Examples
 
-```js
+```kcl
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [20, 0])
   |> line(end = [0, 3], tag = $thing)
   |> line(end = [-10, 0])