Move operations on solids to be declared in KCL (#6462)

* Declare chamfer in KCL

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

* Ignore more in the simulation tests

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

* Declare fillet in KCL

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

* Move shell and hollow to KCL

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

---------

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

.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

@@ -15,8 +15,12 @@ name: cargo test
 jobs:
   cargotest:
     name: cargo test
-    runs-on: ubuntu-latest-8-cores
+    runs-on:
+      - runs-on=${{ github.run_id }}
+      - runner=32cpu-linux-x64
+      - extras=s3-cache
     steps:
+      - uses: runs-on/action@v1
       - uses: actions/create-github-app-token@v1
         id: app-token
         with:
@@ -81,11 +85,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,16 +121,14 @@ 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'
         shell: bash
         run: |-
           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 llvm-cov nextest --workspace --features artifact-graph --lcov --output-path lcov.info --retries=2 --no-fail-fast -P ci 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

.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
@@ -283,23 +282,37 @@ jobs:
       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/abs.md

@@ -9,7 +9,7 @@ Compute the absolute value of a number.
 
 
 ```js
-abs(num: number): number
+abs(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ abs(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute the absolute value of. | Yes |
 
 ### Returns
 
@@ -34,7 +34,7 @@ abs(num: number): number
 myAngle = -120
 
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [8, 0])
   |> angledLine(angle = abs(myAngle), length = 5)
   |> line(end = [-5, 0])

docs/kcl/acos.md

@@ -9,7 +9,7 @@ Compute the arccosine of a number (in radians).
 
 
 ```js
-acos(num: number): number
+acos(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ acos(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute arccosine of. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ acos(num: number): number
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = toDegrees(acos(0.5)), length = 10)
   |> line(end = [5, 0])
   |> line(endAbsolute = [12, 0])

docs/kcl/angleToMatchLengthX.md

@@ -34,7 +34,7 @@ angleToMatchLengthX(
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [2, 5], tag = $seg01)
   |> angledLine(angle = -angleToMatchLengthX(seg01, 7, %), endAbsoluteX = 10)
   |> close()

docs/kcl/angleToMatchLengthY.md

@@ -34,7 +34,7 @@ angleToMatchLengthY(
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [1, 2], tag = $seg01)
   |> angledLine(angle = angleToMatchLengthY(seg01, 15, %), length = 5)
   |> yLine(endAbsolute = 0)

docs/kcl/angledLine.md

@@ -44,7 +44,7 @@ angledLine(
 
 ```js
 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

@@ -38,7 +38,7 @@ angledLineThatIntersects(
 
 ```js
 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/arc.md

@@ -44,7 +44,7 @@ arc(
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> arc(angleStart = 0, angleEnd = 280, radius = 16)
   |> close()
@@ -55,7 +55,7 @@ example = extrude(exampleSketch, length = 10)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> arc(endAbsolute = [10, 0], interiorAbsolute = [5, 5])
   |> close()
 example = extrude(exampleSketch, length = 10)

docs/kcl/asin.md

@@ -9,7 +9,7 @@ Compute the arcsine of a number (in radians).
 
 
 ```js
-asin(num: number): number
+asin(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ asin(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute arcsine of. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ asin(num: number): number
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = toDegrees(asin(0.5)), length = 20)
   |> yLine(endAbsolute = 0)
   |> close()

docs/kcl/atan.md

@@ -6,10 +6,10 @@ layout: manual
 
 Compute the arctangent of a number (in radians).
 
-
+Consider using `atan2()` instead for the true inverse of tangent.
 
 ```js
-atan(num: number): number
+atan(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ atan(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute arctangent of. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ atan(num: number): number
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = toDegrees(atan(1.25)), length = 20)
   |> yLine(endAbsolute = 0)
   |> close()

docs/kcl/atan2.md

@@ -36,7 +36,7 @@ atan2(
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = toDegrees(atan2(y = 1.25, x = 2)), length = 20)
   |> yLine(endAbsolute = 0)
   |> close()

docs/kcl/bezierCurve.md

@@ -38,7 +38,7 @@ bezierCurve(
 
 ```js
 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/ceil.md

@@ -9,7 +9,7 @@ Compute the smallest integer greater than or equal to a number.
 
 
 ```js
-ceil(num: number): number
+ceil(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ ceil(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to round. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ ceil(num: number): number
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(endAbsolute = [12, 10])
   |> line(end = [ceil(7.02986), 0])
   |> yLine(endAbsolute = 0)

docs/kcl/close.md

@@ -32,7 +32,7 @@ close(
 
 ```js
 startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 10])
   |> line(end = [10, 0])
   |> close()
@@ -43,7 +43,7 @@ startSketchOn(XZ)
 
 ```js
 exampleSketch = startSketchOn(-XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> line(end = [0, 10])
   |> close()

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

@@ -16,7 +16,7 @@ std::math::E: number = 2.71828182845904523536028747135266250_
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 30,
     length = 2 * E ^ 2,

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

@@ -16,7 +16,7 @@ std::math::TAU: number = 6.28318530717958647692528676655900577_
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 50,
     length = 10 * TAU,

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/extrude.md

@@ -40,7 +40,7 @@ extrude(
 
 ```js
 example = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> arc(angleStart = 120, angleEnd = 0, radius = 5)
   |> line(end = [5, 0])
@@ -55,7 +55,7 @@ example = startSketchOn(XZ)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([-10, 0], %)
+  |> startProfile(at = [-10, 0])
   |> arc(angleStart = 120, angleEnd = -60, radius = 5)
   |> line(end = [10, 0])
   |> line(end = [5, 0])
@@ -71,7 +71,7 @@ example = extrude(exampleSketch, length = 10)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([-10, 0], %)
+  |> startProfile(at = [-10, 0])
   |> arc(angleStart = 120, angleEnd = -60, radius = 5)
   |> line(end = [10, 0])
   |> line(end = [5, 0])
@@ -87,7 +87,7 @@ example = extrude(exampleSketch, length = 20, symmetric = true)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([-10, 0], %)
+  |> startProfile(at = [-10, 0])
   |> arc(angleStart = 120, angleEnd = -60, radius = 5)
   |> line(end = [10, 0])
   |> line(end = [5, 0])

docs/kcl/floor.md

@@ -9,7 +9,7 @@ Compute the largest integer less than or equal to a number.
 
 
 ```js
-floor(num: number): number
+floor(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ floor(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to round. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ floor(num: number): number
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(endAbsolute = [12, 10])
   |> line(end = [floor(7.02986), 0])
   |> yLine(endAbsolute = 0)

docs/kcl/getCommonEdge.md

@@ -32,7 +32,7 @@ getCommonEdge(faces: [TagIdentifier]): Uuid
 
 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

@@ -9,7 +9,7 @@ Get the next adjacent edge to the edge given.
 
 
 ```js
-getNextAdjacentEdge(tag: TagIdentifier): Uuid
+getNextAdjacentEdge(edge: TagIdentifier): 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
 
@@ -28,7 +28,7 @@ getNextAdjacentEdge(tag: TagIdentifier): Uuid
 
 ```js
 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

@@ -9,7 +9,7 @@ Get the opposite edge to the edge given.
 
 
 ```js
-getOppositeEdge(tag: TagIdentifier): Uuid
+getOppositeEdge(edge: TagIdentifier): 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
 
@@ -28,7 +28,7 @@ getOppositeEdge(tag: TagIdentifier): Uuid
 
 ```js
 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

@@ -9,7 +9,7 @@ Get the previous adjacent edge to the edge given.
 
 
 ```js
-getPreviousAdjacentEdge(tag: TagIdentifier): Uuid
+getPreviousAdjacentEdge(edge: TagIdentifier): 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
 
@@ -28,7 +28,7 @@ getPreviousAdjacentEdge(tag: TagIdentifier): Uuid
 
 ```js
 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

@@ -32,8 +32,6 @@ layout: manual
   * [`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)
@@ -45,19 +43,16 @@ layout: manual
   * [`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)
@@ -74,7 +69,7 @@ layout: manual
   * [`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)
@@ -102,11 +97,11 @@ 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)
@@ -133,6 +128,11 @@ layout: manual
 * **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)

docs/kcl/intersect.md

@@ -36,7 +36,7 @@ intersect(
 
 fn cube(center, size) {
   return startSketchOn(XY)
-    |> startProfileAt([center[0] - size, center[1] - size], %)
+    |> startProfile(at = [center[0] - size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] + size])
     |> line(endAbsolute = [center[0] - size, center[1] + size])
@@ -61,7 +61,7 @@ intersectedPart = intersect([part001, part002])
 
 fn cube(center, size) {
   return startSketchOn(XY)
-    |> startProfileAt([center[0] - size, center[1] - size], %)
+    |> startProfile(at = [center[0] - size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] + size])
     |> line(endAbsolute = [center[0] - size, center[1] + size])

docs/kcl/involuteCircular.md

@@ -42,7 +42,7 @@ involuteCircular(
 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

@@ -28,7 +28,7 @@ lastSegX(sketch: Sketch): number
 
 ```js
 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

@@ -28,7 +28,7 @@ lastSegY(sketch: Sketch): number
 
 ```js
 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

@@ -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
 
@@ -35,7 +35,7 @@ legAngX(
 ### Examples
 
 ```js
-legAngX(5, 3)
+legAngX(hypotenuse = 5, leg = 3)
 ```
 
 

docs/kcl/legAngY.md

@@ -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
 
@@ -35,7 +35,7 @@ legAngY(
 ### Examples
 
 ```js
-legAngY(5, 3)
+legAngY(hypotenuse = 5, leg = 3)
 ```
 
 

docs/kcl/legLen.md

@@ -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
 
@@ -35,7 +35,7 @@ legLen(
 ### Examples
 
 ```js
-legLen(5, 3)
+legLen(hypotenuse = 5, leg = 3)
 ```
 
 

docs/kcl/line.md

@@ -36,7 +36,7 @@ line(
 
 ```js
 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/ln.md

@@ -9,7 +9,7 @@ Compute the natural logarithm of the number.
 
 
 ```js
-ln(num: number): number
+ln(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ ln(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute the logarithm of. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ ln(num: number): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [ln(100), 15])
   |> line(end = [5, -6])
   |> line(end = [-10, -10])

docs/kcl/loft.md

@@ -43,7 +43,7 @@ loft(
 ```js
 // Loft a square and a triangle.
 squareSketch = startSketchOn(XY)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])
@@ -51,7 +51,7 @@ squareSketch = startSketchOn(XY)
   |> close()
 
 triangleSketch = startSketchOn(offsetPlane(XY, offset = 75))
-  |> startProfileAt([0, 125], %)
+  |> startProfile(at = [0, 125])
   |> line(end = [-15, -30])
   |> line(end = [30, 0])
   |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
@@ -65,7 +65,7 @@ loft([squareSketch, triangleSketch])
 ```js
 // Loft a square, a circle, and another circle.
 squareSketch = startSketchOn(XY)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])
@@ -90,7 +90,7 @@ loft([
 ```js
 // Loft a square, a circle, and another circle with options.
 squareSketch = startSketchOn(XY)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])

docs/kcl/log.md

@@ -10,7 +10,7 @@ The result might not be correctly rounded owing to implementation details; `log2
 
 ```js
 log(
-  num: number,
+  input: number,
   base: number,
 ): number
 ```
@@ -24,8 +24,8 @@ log(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
-| `base` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute the logarithm of. | Yes |
+| `base` | [`number`](/docs/kcl/types/number) | The base of the logarithm. | Yes |
 
 ### Returns
 
@@ -36,8 +36,8 @@ log(
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
-  |> line(end = [log(100, 5), 0])
+  |> startProfile(at = [0, 0])
+  |> line(end = [log(100, base = 5), 0])
   |> line(end = [5, 8])
   |> line(end = [-10, 0])
   |> close()

docs/kcl/log10.md

@@ -32,7 +32,7 @@ log10(num: number): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [log10(100), 0])
   |> line(end = [5, 8])
   |> line(end = [-10, 0])

docs/kcl/log2.md

@@ -9,7 +9,7 @@ Compute the base 2 logarithm of the number.
 
 
 ```js
-log2(num: number): number
+log2(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ log2(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute the logarithm of. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ log2(num: number): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [log2(100), 0])
   |> line(end = [5, 8])
   |> line(end = [-10, 0])

docs/kcl/max.md

@@ -9,7 +9,7 @@ Compute the maximum of the given arguments.
 
 
 ```js
-max(args: [number]): number
+max(input: [number]): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ max(args: [number]): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `args` | [`[number]`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`[number]`](/docs/kcl/types/number) | An array of numbers to compute the maximum of. | Yes |
 
 ### Returns
 
@@ -32,8 +32,8 @@ max(args: [number]): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
-  |> angledLine(angle = 70, length = max(15, 31, 4, 13, 22))
+  |> startProfile(at = [0, 0])
+  |> angledLine(angle = 70, length = max([15, 31, 4, 13, 22]))
   |> line(end = [20, 0])
   |> close()
 

docs/kcl/min.md

@@ -9,7 +9,7 @@ Compute the minimum of the given arguments.
 
 
 ```js
-min(args: [number]): number
+min(input: [number]): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ min(args: [number]): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `args` | [`[number]`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`[number]`](/docs/kcl/types/number) | An array of numbers to compute the minimum of. | Yes |
 
 ### Returns
 
@@ -32,8 +32,8 @@ min(args: [number]): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
-  |> angledLine(angle = 70, length = min(15, 31, 4, 13, 22))
+  |> startProfile(at = [0, 0])
+  |> angledLine(angle = 70, length = min([15, 31, 4, 13, 22]))
   |> line(end = [20, 0])
   |> close()
 

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/offsetPlane.md

@@ -33,7 +33,7 @@ offsetPlane(
 ```js
 // Loft a square and a circle on the `XY` plane using offset.
 squareSketch = startSketchOn(XY)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])
@@ -51,7 +51,7 @@ loft([squareSketch, circleSketch])
 ```js
 // Loft a square and a circle on the `XZ` plane using offset.
 squareSketch = startSketchOn(XZ)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])
@@ -69,7 +69,7 @@ loft([squareSketch, circleSketch])
 ```js
 // Loft a square and a circle on the `YZ` plane using offset.
 squareSketch = startSketchOn(YZ)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])
@@ -87,7 +87,7 @@ loft([squareSketch, circleSketch])
 ```js
 // Loft a square and a circle on the `-XZ` plane using offset.
 squareSketch = startSketchOn(-XZ)
-  |> startProfileAt([-100, 200], %)
+  |> startProfile(at = [-100, 200])
   |> line(end = [200, 0])
   |> line(end = [0, -200])
   |> line(end = [-200, 0])
@@ -105,12 +105,12 @@ loft([squareSketch, circleSketch])
 ```js
 // A circle on the XY plane
 startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> circle(radius = 10, center = [0, 0])
 
 // Triangle on the plane 4 units above
 startSketchOn(offsetPlane(XY, offset = 4))
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> line(end = [0, 10])
   |> close()

docs/kcl/patternCircular2d.md

@@ -40,7 +40,7 @@ patternCircular2d(
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([.5, 25], %)
+  |> startProfile(at = [.5, 25])
   |> line(end = [0, 5])
   |> line(end = [-1, 0])
   |> line(end = [0, -5])

docs/kcl/patternLinear3d.md

@@ -38,7 +38,7 @@ patternLinear3d(
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [0, 2])
   |> line(end = [3, 1])
   |> line(end = [0, -4])
@@ -54,7 +54,7 @@ example = extrude(exampleSketch, length = 1)
 // Pattern a whole sketch on face.
 size = 100
 case = startSketchOn(XY)
-  |> startProfileAt([-size, -size], %)
+  |> startProfile(at = [-size, -size])
   |> line(end = [2 * size, 0])
   |> line(end = [0, 2 * size])
   |> tangentialArc(endAbsolute = [-size, size])
@@ -85,7 +85,7 @@ patternLinear3d(
 // Pattern an object on a face.
 size = 100
 case = startSketchOn(XY)
-  |> startProfileAt([-size, -size], %)
+  |> startProfile(at = [-size, -size])
   |> line(end = [2 * size, 0])
   |> line(end = [0, 2 * size])
   |> tangentialArc(endAbsolute = [-size, size])

docs/kcl/patternTransform.md

@@ -102,7 +102,7 @@ fn cube(length, center) {
   p3 = [l + x, -l + y]
 
   return startSketchOn(XY)
-    |> startProfileAt(p0, %)
+    |> startProfile(at = p0)
     |> line(endAbsolute = p1)
     |> line(endAbsolute = p2)
     |> line(endAbsolute = p3)
@@ -117,7 +117,11 @@ fn transform(i) {
     // Move down each time.
     translate = [0, 0, -i * width],
     // Make the cube longer, wider and flatter each time.
-    scale = [pow(1.1, i), pow(1.1, i), pow(0.9, i)],
+    scale = [
+      pow(1.1, exp = i),
+      pow(1.1, exp = i),
+      pow(0.9, exp = i)
+    ],
     // Turn by 15 degrees each time.
     rotation = { angle = 15 * i, origin = "local" }
   }
@@ -140,7 +144,7 @@ fn cube(length, center) {
   p3 = [l + x, -l + y]
 
   return startSketchOn(XY)
-    |> startProfileAt(p0, %)
+    |> startProfile(at = p0)
     |> line(endAbsolute = p1)
     |> line(endAbsolute = p2)
     |> line(endAbsolute = p3)
@@ -204,7 +208,7 @@ fn transform(i) {
   ]
 }
 startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> polygon(
        radius = 10,
        numSides = 4,

docs/kcl/pop.md

@@ -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
 

docs/kcl/pow.md

@@ -10,8 +10,8 @@ Compute the number to a power.
 
 ```js
 pow(
-  num: number,
-  pow: number,
+  input: number,
+  exp: number,
 ): number
 ```
 
@@ -24,8 +24,8 @@ pow(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
-| `pow` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to raise. | Yes |
+| `exp` | [`number`](/docs/kcl/types/number) | The power to raise to. | Yes |
 
 ### Returns
 
@@ -36,8 +36,8 @@ pow(
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
-  |> angledLine(angle = 50, length = pow(5, 2))
+  |> startProfile(at = [0, 0])
+  |> angledLine(angle = 50, length = pow(5, exp = 2))
   |> yLine(endAbsolute = 0)
   |> close()
 

docs/kcl/profileStart.md

@@ -28,7 +28,7 @@ profileStart(profile: Sketch): [number]
 
 ```js
 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

@@ -28,7 +28,7 @@ profileStartX(profile: Sketch): number
 
 ```js
 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

@@ -28,7 +28,7 @@ profileStartY(profile: Sketch): number
 
 ```js
 sketch001 = startSketchOn(XY)
-  |> startProfileAt([5, 2], %)
+  |> startProfile(at = [5, 2])
   |> angledLine(angle = -60, length = 14)
   |> angledLine(angle = 30, endAbsoluteY = profileStartY(%))
 ```

docs/kcl/push.md

@@ -11,7 +11,7 @@ Returns a new array with the element appended.
 ```js
 push(
   array: [KclValue],
-  elem: KclValue,
+  item: KclValue,
 ): 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
 
@@ -32,7 +32,7 @@ push(
 
 ```js
 arr = [1, 2, 3]
-new_arr = push(arr, 4)
+new_arr = push(arr, item = 4)
 assert(
   new_arr[3],
   isEqualTo = 4,

docs/kcl/reduce.md

@@ -11,8 +11,8 @@ Take a starting value. Then, for each element of an array, calculate the next va
 ```js
 reduce(
   array: [KclValue],
-  start: KclValue,
-  reduceFn: FunctionSource,
+  initial: KclValue,
+  f: FunctionSource,
 ): KclValue
 ```
 
@@ -21,9 +21,9 @@ reduce(
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `array` | [`[KclValue]`](/docs/kcl/types/KclValue) |  | Yes |
-| `start` | [`KclValue`](/docs/kcl/types/KclValue) | Any KCL value. | Yes |
-| `reduceFn` | `FunctionSource` |  | Yes |
+| `array` | [`[KclValue]`](/docs/kcl/types/KclValue) | Each element of this array gets run through the function `f`, combined with the previous output from `f`, and then used for the next run. | Yes |
+| `initial` | [`KclValue`](/docs/kcl/types/KclValue) | The first time `f` is run, it will be called with the first item of `array` and this initial starting value. | Yes |
+| `f` | `FunctionSource` | Run once per item in the input `array`. This function takes an item from the array, and the previous output from `f` (or `initial` on the very first run). The final time `f` is run, its output is returned as the final output from `reduce`. | Yes |
 
 ### Returns
 
@@ -42,7 +42,7 @@ fn add(a, b) {
 // It uses the `reduce` function, to call the `add` function on every
 // element of the `arr` parameter. The starting value is 0.
 fn sum(arr) {
-  return reduce(arr, 0, add)
+  return reduce(arr, initial = 0, f = add)
 }
 
 /* The above is basically like this pseudo-code:
@@ -69,9 +69,13 @@ assert(
 // an anonymous `add` function as its parameter, instead of declaring a
 // named function outside.
 arr = [1, 2, 3]
-sum = reduce(arr, 0, fn(i, result_so_far) {
-  return i + result_so_far
-})
+sum = reduce(
+  arr,
+  initial = 0,
+  f = fn(i, result_so_far) {
+    return i + result_so_far
+  },
+)
 
 // We use `assert` to check that our `sum` function gives the
 // expected result. It's good to check your work!
@@ -93,17 +97,21 @@ fn decagon(radius) {
 
   // Start the decagon sketch at this point.
   startOfDecagonSketch = startSketchOn(XY)
-    |> startProfileAt([cos(0) * radius, sin(0) * radius], %)
+    |> startProfile(at = [cos(0) * radius, sin(0) * radius])
 
     // Use a `reduce` to draw the remaining decagon sides.
     // For each number in the array 1..10, run the given function,
   // which takes a partially-sketched decagon and adds one more edge to it.
-  fullDecagon = reduce([1..10], startOfDecagonSketch, fn(i, partialDecagon) {
-    // Draw one edge of the decagon.
-    x = cos(stepAngle * i) * radius
-    y = sin(stepAngle * i) * radius
-    return line(partialDecagon, end = [x, y])
-  })
+  fullDecagon = reduce(
+    [1..10],
+    initial = startOfDecagonSketch,
+    f = fn(i, partialDecagon) {
+      // Draw one edge of the decagon.
+      x = cos(stepAngle * i) * radius
+      y = sin(stepAngle * i) * radius
+      return line(partialDecagon, end = [x, y])
+    },
+  )
 
   return fullDecagon
 }
@@ -112,7 +120,7 @@ fn decagon(radius) {
 fn decagon(radius):
     stepAngle = (1/10) * TAU
     plane = startSketchOn('XY')
-    startOfDecagonSketch = startProfileAt([(cos(0)*radius), (sin(0) * radius)], plane)
+    startOfDecagonSketch = startProfile(plane, at = [(cos(0)*radius), (sin(0) * radius)])
 
     // Here's the reduce part.
     partialDecagon = startOfDecagonSketch

docs/kcl/rotate.md

@@ -63,7 +63,7 @@ rotate(
 
 // Create a path for the sweep.
 sweepPath = startSketchOn(XZ)
-  |> startProfileAt([0.05, 0.05], %)
+  |> startProfile(at = [0.05, 0.05])
   |> line(end = [0, 7])
   |> tangentialArc(angle = 90, radius = 5)
   |> line(end = [-3, 0])
@@ -76,7 +76,7 @@ pipeHole = startSketchOn(XY)
 
 sweepSketch = startSketchOn(XY)
   |> circle(center = [0, 0], radius = 2)
-  |> hole(pipeHole, %)
+  |> subtract2d(tool = pipeHole)
   |> sweep(path = sweepPath)
   |> rotate(roll = 10, pitch = 10, yaw = 90)
 ```
@@ -88,7 +88,7 @@ sweepSketch = startSketchOn(XY)
 
 // Create a path for the sweep.
 sweepPath = startSketchOn(XZ)
-  |> startProfileAt([0.05, 0.05], %)
+  |> startProfile(at = [0.05, 0.05])
   |> line(end = [0, 7])
   |> tangentialArc(angle = 90, radius = 5)
   |> line(end = [-3, 0])
@@ -101,7 +101,7 @@ pipeHole = startSketchOn(XY)
 
 sweepSketch = startSketchOn(XY)
   |> circle(center = [0, 0], radius = 2)
-  |> hole(pipeHole, %)
+  |> subtract2d(tool = pipeHole)
   |> sweep(path = sweepPath)
   |> rotate(roll = 10)
 ```
@@ -113,7 +113,7 @@ sweepSketch = startSketchOn(XY)
 
 // Create a path for the sweep.
 sweepPath = startSketchOn(XZ)
-  |> startProfileAt([0.05, 0.05], %)
+  |> startProfile(at = [0.05, 0.05])
   |> line(end = [0, 7])
   |> tangentialArc(angle = 90, radius = 5)
   |> line(end = [-3, 0])
@@ -126,7 +126,7 @@ pipeHole = startSketchOn(XY)
 
 sweepSketch = startSketchOn(XY)
   |> circle(center = [0, 0], radius = 2)
-  |> hole(pipeHole, %)
+  |> subtract2d(tool = pipeHole)
   |> sweep(path = sweepPath)
   |> rotate(axis = [0, 0, 1.0], angle = 90)
 ```
@@ -150,7 +150,7 @@ cube
 
 
 sketch001 = startSketchOn(XY)
-rectangleSketch = startProfileAt([-200, 23.86], sketch001)
+rectangleSketch = startProfile(sketch001, at = [-200, 23.86])
   |> angledLine(angle = 0, length = 73.47, tag = $rectangleSegmentA001)
   |> angledLine(angle = segAng(rectangleSegmentA001) - 90, length = 50.61)
   |> angledLine(angle = segAng(rectangleSegmentA001), length = -segLen(rectangleSegmentA001))
@@ -160,7 +160,7 @@ rectangleSketch = startProfileAt([-200, 23.86], sketch001)
 circleSketch = circle(sketch001, center = [200, -30.29], radius = 32.63)
 
 sketch002 = startSketchOn(YZ)
-sweepPath = startProfileAt([0, 0], sketch002)
+sweepPath = startProfile(sketch002, at = [0, 0])
   |> yLine(length = 231.81)
   |> tangentialArc(radius = 80, angle = -90)
   |> xLine(length = 384.93)
@@ -178,7 +178,7 @@ rotate(parts, axis = [0, 0, 1.0], angle = 90)
 sketch001 = startSketchOn(XY)
 
 fn square() {
-  return startProfileAt([-10, 10], sketch001)
+  return startProfile(sketch001, at = [-10, 10])
     |> xLine(length = 20)
     |> yLine(length = -20)
     |> xLine(length = -20)

docs/kcl/round.md

@@ -9,7 +9,7 @@ Round a number to the nearest integer.
 
 
 ```js
-round(num: number): number
+round(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ round(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to round. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ round(num: number): number
 
 ```js
 sketch001 = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(endAbsolute = [12, 10])
   |> line(end = [round(7.02986), 0])
   |> yLine(endAbsolute = 0)

docs/kcl/scale.md

@@ -47,7 +47,7 @@ scale(
 
 // Create a path for the sweep.
 sweepPath = startSketchOn(XZ)
-  |> startProfileAt([0.05, 0.05], %)
+  |> startProfile(at = [0.05, 0.05])
   |> line(end = [0, 7])
   |> tangentialArc(angle = 90, radius = 5)
   |> line(end = [-3, 0])
@@ -60,7 +60,7 @@ pipeHole = startSketchOn(XY)
 
 sweepSketch = startSketchOn(XY)
   |> circle(center = [0, 0], radius = 2)
-  |> hole(pipeHole, %)
+  |> subtract2d(tool = pipeHole)
   |> sweep(path = sweepPath)
   |> scale(z = 2.5)
 ```
@@ -84,7 +84,7 @@ cube
 
 
 sketch001 = startSketchOn(XY)
-rectangleSketch = startProfileAt([-200, 23.86], sketch001)
+rectangleSketch = startProfile(sketch001, at = [-200, 23.86])
   |> angledLine(angle = 0, length = 73.47, tag = $rectangleSegmentA001)
   |> angledLine(angle = segAng(rectangleSegmentA001) - 90, length = 50.61)
   |> angledLine(angle = segAng(rectangleSegmentA001), length = -segLen(rectangleSegmentA001))
@@ -94,7 +94,7 @@ rectangleSketch = startProfileAt([-200, 23.86], sketch001)
 circleSketch = circle(sketch001, center = [200, -30.29], radius = 32.63)
 
 sketch002 = startSketchOn(YZ)
-sweepPath = startProfileAt([0, 0], sketch002)
+sweepPath = startProfile(sketch002, at = [0, 0])
   |> yLine(length = 231.81)
   |> tangentialArc(radius = 80, angle = -90)
   |> xLine(length = 384.93)

docs/kcl/segAng.md

@@ -28,7 +28,7 @@ segAng(tag: TagIdentifier): number
 
 ```js
 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

@@ -29,7 +29,7 @@ segEnd(tag: TagIdentifier): [number]
 ```js
 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

@@ -28,7 +28,7 @@ segEndX(tag: TagIdentifier): number
 
 ```js
 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

@@ -28,7 +28,7 @@ segEndY(tag: TagIdentifier): number
 
 ```js
 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

@@ -28,7 +28,7 @@ segLen(tag: TagIdentifier): number
 
 ```js
 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

@@ -29,7 +29,7 @@ segStart(tag: TagIdentifier): [number]
 ```js
 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

@@ -28,7 +28,7 @@ segStartX(tag: TagIdentifier): number
 
 ```js
 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

@@ -28,7 +28,7 @@ segStartY(tag: TagIdentifier): number
 
 ```js
 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/sqrt.md

@@ -9,7 +9,7 @@ Compute the square root of a number.
 
 
 ```js
-sqrt(num: number): number
+sqrt(input: number): number
 ```
 
 ### Tags
@@ -21,7 +21,7 @@ sqrt(num: number): number
 
 | Name | Type | Description | Required |
 |----------|------|-------------|----------|
-| `num` | [`number`](/docs/kcl/types/number) |  | Yes |
+| `input` | [`number`](/docs/kcl/types/number) | The number to compute the square root of. | Yes |
 
 ### Returns
 
@@ -32,7 +32,7 @@ sqrt(num: number): number
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(angle = 50, length = sqrt(2500))
   |> yLine(endAbsolute = 0)
   |> close()

docs/kcl/startSketchOn.md

@@ -40,7 +40,7 @@ startSketchOn(
 
 ```js
 exampleSketch = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> line(end = [0, 10])
   |> line(end = [-10, 0])
@@ -49,7 +49,7 @@ exampleSketch = startSketchOn(XY)
 example = extrude(exampleSketch, length = 5)
 
 exampleSketch002 = startSketchOn(example, face = END)
-  |> startProfileAt([1, 1], %)
+  |> startProfile(at = [1, 1])
   |> line(end = [8, 0])
   |> line(end = [0, 8])
   |> line(end = [-8, 0])
@@ -58,7 +58,7 @@ exampleSketch002 = startSketchOn(example, face = END)
 example002 = extrude(exampleSketch002, length = 5)
 
 exampleSketch003 = startSketchOn(example002, face = END)
-  |> startProfileAt([2, 2], %)
+  |> startProfile(at = [2, 2])
   |> line(end = [6, 0])
   |> line(end = [0, 6])
   |> line(end = [-6, 0])
@@ -74,7 +74,7 @@ example003 = extrude(exampleSketch003, length = 5)
 
 
 exampleSketch = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> line(end = [0, 10])
   |> line(end = [-10, 0])
@@ -83,7 +83,7 @@ exampleSketch = startSketchOn(XY)
 example = extrude(exampleSketch, length = 5, tagEnd = $end01)
 
 exampleSketch002 = startSketchOn(example, face = end01)
-  |> startProfileAt([1, 1], %)
+  |> startProfile(at = [1, 1])
   |> line(end = [8, 0])
   |> line(end = [0, 8])
   |> line(end = [-8, 0])
@@ -92,7 +92,7 @@ exampleSketch002 = startSketchOn(example, face = end01)
 example002 = extrude(exampleSketch002, length = 5, tagEnd = $end02)
 
 exampleSketch003 = startSketchOn(example002, face = end02)
-  |> startProfileAt([2, 2], %)
+  |> startProfile(at = [2, 2])
   |> line(end = [6, 0])
   |> line(end = [0, 6])
   |> line(end = [-6, 0])
@@ -105,7 +105,7 @@ example003 = extrude(exampleSketch003, length = 5)
 
 ```js
 exampleSketch = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0])
   |> line(end = [0, 10], tag = $sketchingFace)
   |> line(end = [-10, 0])
@@ -114,7 +114,7 @@ exampleSketch = startSketchOn(XY)
 example = extrude(exampleSketch, length = 10)
 
 exampleSketch002 = startSketchOn(example, face = sketchingFace)
-  |> startProfileAt([1, 1], %)
+  |> startProfile(at = [1, 1])
   |> line(end = [8, 0])
   |> line(end = [0, 8])
   |> line(end = [-8, 0])
@@ -123,7 +123,7 @@ exampleSketch002 = startSketchOn(example, face = sketchingFace)
 example002 = extrude(exampleSketch002, length = 10)
 
 exampleSketch003 = startSketchOn(example002, face = sketchingFace002)
-  |> startProfileAt([-8, 12], %)
+  |> startProfile(at = [-8, 12])
   |> line(end = [0, 6])
   |> line(end = [6, 0])
   |> line(end = [0, -6])
@@ -136,7 +136,7 @@ example003 = extrude(exampleSketch003, length = 5)
 
 ```js
 exampleSketch = startSketchOn(XY)
-  |> startProfileAt([4, 12], %)
+  |> startProfile(at = [4, 12])
   |> line(end = [2, 0])
   |> line(end = [0, -6])
   |> line(end = [4, -6])
@@ -149,7 +149,7 @@ exampleSketch = startSketchOn(XY)
 example = revolve(exampleSketch, axis = Y, angle = 180)
 
 exampleSketch002 = startSketchOn(example, face = END)
-  |> startProfileAt([4.5, -5], %)
+  |> startProfile(at = [4.5, -5])
   |> line(end = [0, 5])
   |> line(end = [5, 0])
   |> line(end = [0, -5])
@@ -165,7 +165,7 @@ example002 = extrude(exampleSketch002, length = 5)
 
 
 exampleSketch = startSketchOn(XY)
-  |> startProfileAt([4, 12], %)
+  |> startProfile(at = [4, 12])
   |> line(end = [2, 0])
   |> line(end = [0, -6])
   |> line(end = [4, -6])
@@ -183,7 +183,7 @@ example = revolve(
 )
 
 exampleSketch002 = startSketchOn(example, face = end01)
-  |> startProfileAt([4.5, -5], %)
+  |> startProfile(at = [4.5, -5])
   |> line(end = [0, 5])
   |> line(end = [5, 0])
   |> line(end = [0, -5])
@@ -201,7 +201,7 @@ a1 = startSketchOn({
        yAxis = { x = 0, y = 1, z = 0 },
        zAxis = { x = 0, y = 0, z = 1 }
      })
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [100.0, 0])
   |> yLine(length = -100.0)
   |> xLine(length = -100.0)

docs/kcl/std-helix.md

@@ -62,7 +62,7 @@ springSketch = startSketchOn(YZ)
 ```js
 // Create a helix around an edge.
 helper001 = startSketchOn(XZ)
- |> startProfileAt([0, 0], %)
+ |> startProfile(at = [0, 0])
  |> line(end = [0, 10], tag = $edge001)
 
 helixPath = helix(

docs/kcl/std-math-cos.md

@@ -28,7 +28,7 @@ cos(@num: number(Angle)): number(_)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 30,
     length = 3 / cos(30deg),

docs/kcl/std-math-polar.md

@@ -33,7 +33,7 @@ polar(
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = polar(angle = 30, length = 5), tag = $thing)
   |> line(end = [0, 5])
   |> line(end = [segEndX(thing), 0])

docs/kcl/std-math-sin.md

@@ -28,7 +28,7 @@ sin(@num: number(Angle)): number(_)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 50,
     length = 15 / sin(135deg),

docs/kcl/std-math-tan.md

@@ -28,7 +28,7 @@ tan(@num: number(Angle)): number(_)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 50,
     length = 50 * tan((1/2): number(rad)),

docs/kcl/std-revolve.md

@@ -53,7 +53,7 @@ revolve(
 
 ```js
 part001 = startSketchOn(XY)
-    |> startProfileAt([4, 12], %)
+    |> startProfile(at = [4, 12])
     |> line(end = [2, 0])
     |> line(end = [0, -6])
     |> line(end = [4, -6])
@@ -81,7 +81,7 @@ sketch001 = startSketchOn(XY)
 
 ```js
 part001 = startSketchOn(XY)
-    |> startProfileAt([4, 12], %)
+    |> startProfile(at = [4, 12])
     |> line(end = [2, 0])
     |> line(end = [0, -6])
     |> line(end = [4, -6])
@@ -97,7 +97,7 @@ part001 = startSketchOn(XY)
 
 ```js
 part001 = startSketchOn(XY)
-    |> startProfileAt([4, 12], %)
+    |> startProfile(at = [4, 12])
     |> line(end = [2, 0])
     |> line(end = [0, -6])
     |> line(end = [4, -6])
@@ -109,7 +109,7 @@ part001 = startSketchOn(XY)
     |> revolve(axis = Y, angle = 180)
 
 part002 = startSketchOn(part001, face = END)
-    |> startProfileAt([4.5, -5], %)
+    |> startProfile(at = [4.5, -5])
     |> line(end = [0, 5])
     |> line(end = [5, 0])
     |> line(end = [0, -5])
@@ -121,7 +121,7 @@ part002 = startSketchOn(part001, face = END)
 
 ```js
 box = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20])
     |> line(end = [20, 0])
     |> line(end = [0, -20])
@@ -140,7 +140,7 @@ sketch001 = startSketchOn(box, face = END)
 
 ```js
 box = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20])
     |> line(end = [20, 0])
     |> line(end = [0, -20], tag = $revolveAxis)
@@ -159,7 +159,7 @@ sketch001 = startSketchOn(box, face = END)
 
 ```js
 box = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20])
     |> line(end = [20, 0])
     |> line(end = [0, -20], tag = $revolveAxis)
@@ -179,7 +179,7 @@ sketch001 = startSketchOn(box, face = END)
 
 ```js
 sketch001 = startSketchOn(XY)
-  |> startProfileAt([10, 0], %)
+  |> startProfile(at = [10, 0])
   |> line(end = [5, -5])
   |> line(end = [5, 5])
   |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
@@ -200,14 +200,14 @@ part001 = revolve(
 // Revolve two sketches around the same axis.
 
 sketch001 = startSketchOn(XY)
-profile001 = startProfileAt([4, 8], sketch001)
+profile001 = startProfile(sketch001, at = [4, 8])
     |> xLine(length = 3)
     |> yLine(length = -3)
     |> xLine(length = -3)
     |> line(endAbsolute = [profileStartX(%), profileStartY(%)])
     |> close()
 
-profile002 = startProfileAt([-5, 8], sketch001)
+profile002 = startProfile(sketch001, at = [-5, 8])
     |> xLine(length = 3)
     |> yLine(length = -3)
     |> xLine(length = -3)
@@ -226,7 +226,7 @@ revolve(
 // Revolve around a path that has not been extruded.
 
 profile001 = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20], tag = $revolveAxis)
     |> line(end = [20, 0])
     |> line(end = [0, -20])
@@ -243,7 +243,7 @@ sketch001 = startSketchOn(XY)
 // Revolve around a path that has not been extruded or closed.
 
 profile001 = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20], tag = $revolveAxis)
     |> line(end = [20, 0])
 
@@ -258,7 +258,7 @@ sketch001 = startSketchOn(XY)
 // Symmetrically revolve around a path.
 
 profile001 = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20], tag = $revolveAxis)
     |> line(end = [20, 0])
 
@@ -273,7 +273,7 @@ sketch001 = startSketchOn(XY)
 // Bidirectional revolve around a path.
 
 profile001 = startSketchOn(XY)
-    |> startProfileAt([0, 0], %)
+    |> startProfile(at = [0, 0])
     |> line(end = [0, 20], tag = $revolveAxis)
     |> line(end = [20, 0])
 

docs/kcl/std-sketch-circle.md

@@ -46,12 +46,12 @@ example = extrude(exampleSketch, length = 5)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([-15, 0], %)
+  |> startProfile(at = [-15, 0])
   |> line(end = [30, 0])
   |> line(end = [0, 30])
   |> line(end = [-30, 0])
   |> close()
-  |> hole(circle(center = [0, 15], radius = 5), %)
+  |> subtract2d(tool = circle(center = [0, 15], radius = 5))
 
 example = extrude(exampleSketch, length = 5)
 ```

docs/kcl/std-sketch-mirror2d.md

@@ -35,7 +35,7 @@ mirror2d(
 ```js
 // Mirror an un-closed sketch across the Y axis.
 sketch001 = startSketchOn(XZ)
-    |> startProfileAt([0, 10], %)
+    |> startProfile(at = [0, 10])
     |> line(end = [15, 0])
     |> line(end = [-7, -3])
     |> line(end = [9, -1])
@@ -54,7 +54,7 @@ example = extrude(sketch001, length = 10)
 ```js
 // Mirror a un-closed sketch across the Y axis.
 sketch001 = startSketchOn(XZ)
-    |> startProfileAt([0, 8.5], %)
+    |> startProfile(at = [0, 8.5])
     |> line(end = [20, -8.5])
     |> line(end = [-20, -8.5])
     |> mirror2d(axis = Y)
@@ -67,11 +67,11 @@ example = extrude(sketch001, length = 10)
 ```js
 // Mirror a un-closed sketch across an edge.
 helper001 = startSketchOn(XZ)
- |> startProfileAt([0, 0], %)
+ |> startProfile(at = [0, 0])
  |> line(end = [0, 10], tag = $edge001)
 
 sketch001 = startSketchOn(XZ)
-    |> startProfileAt([0, 8.5], %)
+    |> startProfile(at = [0, 8.5])
     |> line(end = [20, -8.5])
     |> line(end = [-20, -8.5])
     |> mirror2d(axis = edge001)
@@ -84,7 +84,7 @@ sketch001 = startSketchOn(XZ)
 ```js
 // Mirror an un-closed sketch across a custom axis.
 sketch001 = startSketchOn(XZ)
-    |> startProfileAt([0, 8.5], %)
+    |> startProfile(at = [0, 8.5])
     |> line(end = [20, -8.5])
     |> line(end = [-20, -8.5])
     |> mirror2d(
@@ -101,7 +101,7 @@ example = extrude(sketch001, length = 10)
 ```js
 // Sketch on the face of a mirrored sketch, that has been extruded.
 sketch0011 = startSketchOn(XY)
-     |> startProfileAt([6.77, 0], %)
+     |> startProfile(at = [6.77, 0])
      |> yLine(length = 1.27)
      |> tangentialArc(endAbsolute = [5.96, 2.37])
      |> tangentialArc(endAbsolute = [-6.2, 2.44])

docs/kcl/std-toDegrees.md

@@ -28,7 +28,7 @@ toDegrees(@num: number(deg)): number(deg)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 50,
     length = 70 * cos(toDegrees((PI/4): number(rad))),

docs/kcl/std-toRadians.md

@@ -28,7 +28,7 @@ toRadians(@num: number(rad)): number(rad)
 
 ```js
 exampleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> angledLine(
     angle = 50,
     length = 70 * cos(toRadians(45)),

docs/kcl/subtract.md

@@ -38,7 +38,7 @@ subtract(
 
 fn cube(center, size) {
   return startSketchOn(XY)
-    |> startProfileAt([center[0] - size, center[1] - size], %)
+    |> startProfile(at = [center[0] - size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] + size])
     |> line(endAbsolute = [center[0] - size, center[1] + size])
@@ -63,7 +63,7 @@ subtractedPart = subtract([part001], tools = [part002])
 
 fn cube(center, size) {
   return startSketchOn(XY)
-    |> startProfileAt([center[0] - size, center[1] - size], %)
+    |> startProfile(at = [center[0] - size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] - size])
     |> line(endAbsolute = [center[0] + size, center[1] + size])
     |> line(endAbsolute = [center[0] - size, center[1] + size])

docs/kcl/sweep.md

@@ -45,7 +45,7 @@ sweep(
 
 // Create a path for the sweep.
 sweepPath = startSketchOn(XZ)
-  |> startProfileAt([0.05, 0.05], %)
+  |> startProfile(at = [0.05, 0.05])
   |> line(end = [0, 7])
   |> tangentialArc(angle = 90, radius = 5)
   |> line(end = [-3, 0])
@@ -58,7 +58,7 @@ pipeHole = startSketchOn(XY)
 
 sweepSketch = startSketchOn(XY)
   |> circle(center = [0, 0], radius = 2)
-  |> hole(pipeHole, %)
+  |> subtract2d(tool = pipeHole)
   |> sweep(path = sweepPath)
 ```
 
@@ -90,7 +90,7 @@ springSketch = startSketchOn(YZ)
 
 
 sketch001 = startSketchOn(XY)
-rectangleSketch = startProfileAt([-200, 23.86], sketch001)
+rectangleSketch = startProfile(sketch001, at = [-200, 23.86])
   |> angledLine(angle = 0, length = 73.47, tag = $rectangleSegmentA001)
   |> angledLine(angle = segAng(rectangleSegmentA001) - 90, length = 50.61)
   |> angledLine(angle = segAng(rectangleSegmentA001), length = -segLen(rectangleSegmentA001))
@@ -100,7 +100,7 @@ rectangleSketch = startProfileAt([-200, 23.86], sketch001)
 circleSketch = circle(sketch001, center = [200, -30.29], radius = 32.63)
 
 sketch002 = startSketchOn(YZ)
-sweepPath = startProfileAt([0, 0], sketch002)
+sweepPath = startProfile(sketch002, at = [0, 0])
   |> yLine(length = 231.81)
   |> tangentialArc(radius = 80, angle = -90)
   |> xLine(length = 384.93)
@@ -118,7 +118,7 @@ sketch001 = startSketchOn(XY)
 circleSketch = circle(sketch001, center = [200, -30.29], radius = 32.63)
 
 sketch002 = startSketchOn(YZ)
-sweepPath = startProfileAt([0, 0], sketch002)
+sweepPath = startProfile(sketch002, at = [0, 0])
   |> yLine(length = 231.81)
   |> tangentialArc(radius = 80, angle = -90)
   |> xLine(length = 384.93)

docs/kcl/tangentToEnd.md

@@ -29,7 +29,7 @@ tangentToEnd(tag: TagIdentifier): number
 ```js
 // Horizontal pill.
 pillSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [20, 0])
   |> tangentialArc(end = [0, 10], tag = $arc1)
   |> angledLine(angle = tangentToEnd(arc1), length = 20)
@@ -44,7 +44,7 @@ pillExtrude = extrude(pillSketch, length = 10)
 ```js
 // Vertical pill.  Use absolute coordinate for arc.
 pillSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [0, 20])
   |> tangentialArc(endAbsolute = [10, 20], tag = $arc1)
   |> angledLine(angle = tangentToEnd(arc1), length = 20)
@@ -58,7 +58,7 @@ pillExtrude = extrude(pillSketch, length = 10)
 
 ```js
 rectangleSketch = startSketchOn(XZ)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> line(end = [10, 0], tag = $seg1)
   |> angledLine(angle = tangentToEnd(seg1), length = 10)
   |> line(end = [0, 10])
@@ -72,7 +72,7 @@ rectangleExtrude = extrude(rectangleSketch, length = 10)
 
 ```js
 bottom = startSketchOn(XY)
-  |> startProfileAt([0, 0], %)
+  |> startProfile(at = [0, 0])
   |> arc(endAbsolute = [10, 10], interiorAbsolute = [5, 1], tag = $arc1)
   |> angledLine(angle = tangentToEnd(arc1), length = 20)
   |> close()
@@ -85,7 +85,7 @@ circSketch = startSketchOn(XY)
   |> circle(center = [0, 0], radius = 3, tag = $circ)
 
 triangleSketch = startSketchOn(XY)
-  |> startProfileAt([-5, 0], %)
+  |> startProfile(at = [-5, 0])
   |> angledLine(angle = tangentToEnd(circ), length = 10)
   |> line(end = [-15, 0])
   |> close()