docs(sdk): render skill siblings in the API-docs generator

.github/scripts/bump_manifests.py

@@ -60,8 +60,8 @@ def bump_json_top_level_version(text: str, new_version: str) -> str:
 def bump_pep440_dep_pin(text: str, dep_name: str, new_pep440: str) -> str:
     """Replace ``"<dep_name>==<old>"`` with ``"<dep_name>==<new_pep440>"``.
 
-    Used for the ``iii-observability`` pin inside the python iii
-    ``pyproject.toml`` ``dependencies = [...]`` array.
+    Replaces a pinned PEP 440 dependency version in a pyproject.toml
+    ``dependencies = [...]`` array.
     """
     line_re = re.compile(rf'"{re.escape(dep_name)}==[^"]*"')
     m = line_re.search(text)
@@ -93,12 +93,14 @@ def bump_go_const_version(text: str, new_version: str) -> str:
     "engine/Cargo.toml",
     "sdk/packages/rust/iii/Cargo.toml",
     "sdk/packages/rust/observability/Cargo.toml",
+    "sdk/packages/rust/helpers/Cargo.toml",
     "console/packages/console-rust/Cargo.toml",
 )
 _JSON_PACKAGE_FILES = (
     "sdk/packages/node/iii/package.json",
     "sdk/packages/node/iii-browser/package.json",
     "sdk/packages/node/observability/package.json",
+    "sdk/packages/node/helpers/package.json",
 )
 
 
@@ -109,34 +111,47 @@ def rewrite_all(root: Path, new_version: str, new_py_version: str) -> None:
         path = root / rel
         path.write_text(bump_cargo_package_version(path.read_text(), new_version))
 
-    # Workspace root: bump both the workspace.package version and the
-    # iii-observability workspace-dep version pin.
+    # Workspace root: bump the workspace.package version and the internal
+    # workspace-dep version pins. The pins are plain "X.Y.Z" requirements, so
+    # they must move to the prerelease too — otherwise `cargo` can't match the
+    # prerelease candidate (e.g. ^0.19.4 won't accept 0.19.4-alpha.1).
     workspace_path = root / "Cargo.toml"
     body = bump_cargo_package_version(workspace_path.read_text(), new_version)
     body = bump_cargo_workspace_dep_version(body, "iii-observability", new_version)
+    body = bump_cargo_workspace_dep_version(body, "iii-helpers", new_version)
     workspace_path.write_text(body)
 
     # JSON package versions
     for rel in _JSON_PACKAGE_FILES:
         path = root / rel
         path.write_text(bump_json_top_level_version(path.read_text(), new_version))
 
-    # Python iii: top-level version + iii-observability pin
+    # Python iii: top-level version + internal pins (== requirements must
+    # move to the prerelease alongside the packages they point at).
+    # Note: iii-observability is no longer a direct dep of Python iii (replaced
+    # by iii-helpers after the observability-into-helpers refactor).
     py_iii = root / "sdk/packages/python/iii/pyproject.toml"
     body = bump_cargo_package_version(py_iii.read_text(), new_py_version)
-    body = bump_pep440_dep_pin(body, "iii-observability", new_py_version)
+    body = bump_pep440_dep_pin(body, "iii-helpers", new_py_version)
     py_iii.write_text(body)
 
-    # Python observability: top-level version only
+    # Python observability: top-level version + iii-helpers dep pin (shim must
+    # depend on the same version of iii-helpers being released alongside it).
     py_obs = root / "sdk/packages/python/observability/pyproject.toml"
-    py_obs.write_text(bump_cargo_package_version(py_obs.read_text(), new_py_version))
+    body = bump_cargo_package_version(py_obs.read_text(), new_py_version)
+    body = bump_pep440_dep_pin(body, "iii-helpers", new_py_version)
+    py_obs.write_text(body)
 
     # Go SDK: keep the reported sdkVersion const in lockstep. The module
     # itself is versioned by its git tag; this only updates the metadata
     # const, using the raw semver (not the PEP 440) version.
     go_client = root / "sdk/packages/go/iii/client.go"
     go_client.write_text(bump_go_const_version(go_client.read_text(), new_version))
 
+    # Python helpers: top-level version only
+    py_helpers = root / "sdk/packages/python/helpers/pyproject.toml"
+    py_helpers.write_text(bump_cargo_package_version(py_helpers.read_text(), new_py_version))
+
 
 import argparse
 import sys

.github/scripts/test_bump_manifests.py

@@ -132,35 +132,55 @@ def test_rewrite_all_updates_every_target_file(tmp_path: Path):
         'version = "0.15.0-next.1"\n\n'
         '[workspace.dependencies]\n'
         'iii-observability = { path = "sdk/packages/rust/observability", version = "0.13.0-next.1" }\n'
+        'iii-helpers = { path = "sdk/packages/rust/helpers", version = "0.13.0-next.1" }\n'
     ))
     _write(root / "engine" / "Cargo.toml", '[package]\nname = "iii"\nversion = "0.15.0-next.1"\n')
     _write(root / "sdk/packages/rust/iii/Cargo.toml", '[package]\nname = "iii-sdk"\nversion = "0.15.0-next.1"\n')
     _write(root / "sdk/packages/rust/observability/Cargo.toml", '[package]\nname = "iii-observability"\nversion = "0.13.0-next.1"\n')
+    _write(root / "sdk/packages/rust/helpers/Cargo.toml", '[package]\nname = "iii-helpers"\nversion = "0.13.0-next.1"\n')
     _write(root / "sdk/packages/node/iii/package.json", '{\n  "name": "iii-sdk",\n  "version": "0.15.0-next.1"\n}\n')
     _write(root / "sdk/packages/node/iii-browser/package.json", '{\n  "name": "iii-browser",\n  "version": "0.15.0-next.1"\n}\n')
     _write(root / "sdk/packages/node/observability/package.json", '{\n  "name": "@iii-dev/observability",\n  "version": "0.13.0-next.1"\n}\n')
+    _write(root / "sdk/packages/node/helpers/package.json", '{\n  "name": "@iii-dev/helpers",\n  "version": "0.13.0-next.1"\n}\n')
+    # Python iii: iii-observability is no longer a direct dep (removed in
+    # observability-into-helpers refactor); only iii-helpers is pinned.
     _write(root / "sdk/packages/python/iii/pyproject.toml", (
         '[project]\nname = "iii-sdk"\nversion = "0.15.0.dev1"\n'
-        'dependencies = [\n    "iii-observability==0.13.0.dev1",\n]\n'
+        'dependencies = [\n    "iii-helpers==0.13.0.dev1",\n]\n'
     ))
-    _write(root / "sdk/packages/python/observability/pyproject.toml", '[project]\nname = "iii-observability"\nversion = "0.13.0.dev1"\n')
+    _write(root / "sdk/packages/python/observability/pyproject.toml", (
+        '[project]\nname = "iii-observability"\nversion = "0.13.0.dev1"\n'
+        'dependencies = [\n    "iii-helpers==0.13.0.dev1",\n]\n\n'
+        '[tool.uv.sources]\niii-helpers = { path = "../helpers", editable = true }\n'
+    ))
+    _write(root / "sdk/packages/python/helpers/pyproject.toml", '[project]\nname = "iii-helpers"\nversion = "0.13.0.dev1"\n')
     _write(root / "console/packages/console-rust/Cargo.toml", '[package]\nname = "console-rust"\nversion = "0.15.0-next.1"\n')
     _write(root / "sdk/packages/go/iii/client.go", 'package iii\n\nconst sdkVersion = "0.1.0"\n')
 
     rewrite_all(root=root, new_version="0.16.0-next.2", new_py_version="0.16.0.dev2")
 
     assert 'version = "0.16.0-next.2"' in (root / "Cargo.toml").read_text()
     assert 'iii-observability = { path = "sdk/packages/rust/observability", version = "0.16.0-next.2" }' in (root / "Cargo.toml").read_text()
+    assert 'iii-helpers = { path = "sdk/packages/rust/helpers", version = "0.16.0-next.2" }' in (root / "Cargo.toml").read_text()
     assert 'version = "0.16.0-next.2"' in (root / "engine" / "Cargo.toml").read_text()
     assert 'version = "0.16.0-next.2"' in (root / "sdk/packages/rust/iii/Cargo.toml").read_text()
     assert 'version = "0.16.0-next.2"' in (root / "sdk/packages/rust/observability/Cargo.toml").read_text()
+    assert 'version = "0.16.0-next.2"' in (root / "sdk/packages/rust/helpers/Cargo.toml").read_text()
     assert '"version": "0.16.0-next.2"' in (root / "sdk/packages/node/iii/package.json").read_text()
     assert '"version": "0.16.0-next.2"' in (root / "sdk/packages/node/iii-browser/package.json").read_text()
     assert '"version": "0.16.0-next.2"' in (root / "sdk/packages/node/observability/package.json").read_text()
+    assert '"version": "0.16.0-next.2"' in (root / "sdk/packages/node/helpers/package.json").read_text()
     py_iii = (root / "sdk/packages/python/iii/pyproject.toml").read_text()
     assert 'version = "0.16.0.dev2"' in py_iii
-    assert '"iii-observability==0.16.0.dev2"' in py_iii
-    assert 'version = "0.16.0.dev2"' in (root / "sdk/packages/python/observability/pyproject.toml").read_text()
+    assert '"iii-helpers==0.16.0.dev2"' in py_iii
+    # iii-observability is published as a shim but is no longer a dep of iii-sdk
+    assert '"iii-observability==' not in py_iii
+    py_obs = (root / "sdk/packages/python/observability/pyproject.toml").read_text()
+    assert 'version = "0.16.0.dev2"' in py_obs
+    # The shim's iii-helpers dep pin must be bumped to the new release version.
+    assert '"iii-helpers==0.16.0.dev2"' in py_obs
+    assert '"iii-helpers==0.13.0.dev1"' not in py_obs
+    assert 'version = "0.16.0.dev2"' in (root / "sdk/packages/python/helpers/pyproject.toml").read_text()
     assert 'version = "0.16.0-next.2"' in (root / "console/packages/console-rust/Cargo.toml").read_text()
     assert 'const sdkVersion = "0.16.0-next.2"' in (root / "sdk/packages/go/iii/client.go").read_text()
 
@@ -172,18 +192,28 @@ def test_cli_invokes_rewrite_all(tmp_path: Path):
         'version = "0.15.0-next.1"\n\n'
         '[workspace.dependencies]\n'
         'iii-observability = { path = "sdk/packages/rust/observability", version = "0.13.0-next.1" }\n'
+        'iii-helpers = { path = "sdk/packages/rust/helpers", version = "0.13.0-next.1" }\n'
     ))
     _write(root / "engine" / "Cargo.toml", 'version = "0.15.0-next.1"\n')
     _write(root / "sdk/packages/rust/iii/Cargo.toml", 'version = "0.15.0-next.1"\n')
     _write(root / "sdk/packages/rust/observability/Cargo.toml", 'version = "0.13.0-next.1"\n')
+    _write(root / "sdk/packages/rust/helpers/Cargo.toml", 'version = "0.13.0-next.1"\n')
     _write(root / "sdk/packages/node/iii/package.json", '{\n  "version": "0.15.0-next.1"\n}\n')
     _write(root / "sdk/packages/node/iii-browser/package.json", '{\n  "version": "0.15.0-next.1"\n}\n')
     _write(root / "sdk/packages/node/observability/package.json", '{\n  "version": "0.13.0-next.1"\n}\n')
+    _write(root / "sdk/packages/node/helpers/package.json", '{\n  "version": "0.13.0-next.1"\n}\n')
+    # Python iii: only iii-helpers is pinned (iii-observability removed in
+    # observability-into-helpers refactor).
     _write(root / "sdk/packages/python/iii/pyproject.toml", (
         'version = "0.15.0.dev1"\n'
-        'dependencies = [\n    "iii-observability==0.13.0.dev1",\n]\n'
+        'dependencies = [\n    "iii-helpers==0.13.0.dev1",\n]\n'
+    ))
+    _write(root / "sdk/packages/python/observability/pyproject.toml", (
+        'version = "0.13.0.dev1"\n'
+        'dependencies = [\n    "iii-helpers==0.13.0.dev1",\n]\n\n'
+        '[tool.uv.sources]\niii-helpers = { path = "../helpers", editable = true }\n'
     ))
-    _write(root / "sdk/packages/python/observability/pyproject.toml", 'version = "0.13.0.dev1"\n')
+    _write(root / "sdk/packages/python/helpers/pyproject.toml", 'version = "0.13.0.dev1"\n')
     _write(root / "console/packages/console-rust/Cargo.toml", 'version = "0.15.0-next.1"\n')
     _write(root / "sdk/packages/go/iii/client.go", 'package iii\n\nconst sdkVersion = "0.1.0"\n')
 
@@ -196,4 +226,5 @@ def test_cli_invokes_rewrite_all(tmp_path: Path):
     assert "0.16.0-next.2" in result.stdout
 
     assert 'version = "0.16.0-next.2"' in (root / "Cargo.toml").read_text()
-    assert 'iii-observability==0.16.0.dev2' in (root / "sdk/packages/python/iii/pyproject.toml").read_text()
+    assert 'iii-helpers==0.16.0.dev2' in (root / "sdk/packages/python/iii/pyproject.toml").read_text()
+    assert 'iii-helpers==0.16.0.dev2' in (root / "sdk/packages/python/observability/pyproject.toml").read_text()

.github/workflows/alpha-release.yml

@@ -169,7 +169,9 @@ jobs:
 
   observability-py:
     name: Observability Python (pypi)
-    needs: prepare
+    # The shim pins iii-helpers at the release version; publish helpers first so
+    # PyPI can resolve the dependency.
+    needs: [prepare, helpers-py]
     if: ${{ !failure() && !cancelled() }}
     uses: ./.github/workflows/_py.yml
     with:
@@ -207,7 +209,9 @@ jobs:
 
   observability-rust:
     name: Observability Rust (cargo)
-    needs: prepare
+    # The shim depends on iii-helpers; cargo publish resolves it from crates.io,
+    # so helpers must be published first.
+    needs: [prepare, helpers-rust]
     if: ${{ !failure() && !cancelled() }}
     uses: ./.github/workflows/_rust-cargo.yml
     with:

.github/workflows/ci.yml

@@ -620,8 +620,8 @@ jobs:
       #- name: Lint
       #  run: npx @biomejs/biome check sdk/packages/node
 
-      - name: Build observability (prerequisite for type check)
-        run: pnpm --filter @iii-dev/observability build
+      - name: Build helper packages (prerequisite for type check)
+        run: pnpm --filter @iii-dev/observability build && pnpm --filter @iii-dev/helpers build
 
       - name: Type check
         run: pnpm --filter iii-sdk exec tsc --noEmit

.github/workflows/create-tag.yml

@@ -74,11 +74,14 @@ jobs:
                      engine/Cargo.toml \
                      sdk/packages/rust/iii/Cargo.toml \
                      sdk/packages/rust/observability/Cargo.toml \
+                     sdk/packages/rust/helpers/Cargo.toml \
                      sdk/packages/node/iii/package.json \
                      sdk/packages/node/iii-browser/package.json \
                      sdk/packages/node/observability/package.json \
+                     sdk/packages/node/helpers/package.json \
                      sdk/packages/python/iii/pyproject.toml \
                      sdk/packages/python/observability/pyproject.toml \
+                     sdk/packages/python/helpers/pyproject.toml \
                      console/packages/console-rust/Cargo.toml \
                      crates/scaffolder-core/Cargo.toml \
                      crates/motia-tools/Cargo.toml; do
@@ -211,13 +214,14 @@ jobs:
           }
 
           check_pep440_pin() {
+            # $1=file $2=dep_name $3=expected_version
             local actual
-            actual=$(grep -oE '"iii-observability==[^"]+"' "$1" | head -n1 | sed -E 's/.*==([^"]+)".*/\1/')
-            if [[ "$actual" != "$2" ]]; then
-              echo "::error::$1 iii-observability pin mismatch: expected $2, got $actual"
+            actual=$(grep -oE "\"${2}==[^\"]+\"" "$1" | head -n1 | sed -E 's/.*==([^"]+)".*/\1/')
+            if [[ "$actual" != "$3" ]]; then
+              echo "::error::$1 ${2} pin mismatch: expected $3, got $actual"
               exit 1
             fi
-            echo "  $1 iii-observability -> $actual"
+            echo "  $1 ${2} -> $actual"
           }
 
           echo "Validating version updates..."
@@ -226,15 +230,19 @@ jobs:
             check_cargo "engine/Cargo.toml" "$VERSION"
             check_cargo "sdk/packages/rust/iii/Cargo.toml" "$VERSION"
             check_cargo "sdk/packages/rust/observability/Cargo.toml" "$VERSION"
+            check_cargo "sdk/packages/rust/helpers/Cargo.toml" "$VERSION"
             check_json "sdk/packages/node/iii/package.json" "$VERSION"
             check_json "sdk/packages/node/iii-browser/package.json" "$VERSION"
             check_json "sdk/packages/node/observability/package.json" "$VERSION"
+            check_json "sdk/packages/node/helpers/package.json" "$VERSION"
             check_cargo "sdk/packages/python/iii/pyproject.toml" "$PY_VERSION"
             check_cargo "sdk/packages/python/observability/pyproject.toml" "$PY_VERSION"
+            check_cargo "sdk/packages/python/helpers/pyproject.toml" "$PY_VERSION"
             check_cargo "console/packages/console-rust/Cargo.toml" "$VERSION"
             check_cargo "Cargo.toml" "$VERSION"
             check_workspace_dep "Cargo.toml" "$VERSION"
-            check_pep440_pin "sdk/packages/python/iii/pyproject.toml" "$PY_VERSION"
+            check_pep440_pin "sdk/packages/python/iii/pyproject.toml" "iii-helpers" "$PY_VERSION"
+            check_pep440_pin "sdk/packages/python/observability/pyproject.toml" "iii-helpers" "$PY_VERSION"
           fi
 
           echo "All versions validated."

.github/workflows/generate-api-docs.yml

@@ -1,10 +1,28 @@
 name: Generate API Docs
 
-# Paused during the 0.12.x docs migration. The 0.11.x SDK API reference
-# (under docs/0-11-0/api-reference/) is frozen; 0.12.x ships with manually
-# authored sdk-reference/ pages. Re-enable the push trigger after the SDK
-# rework lands and the script is repointed at the 0.12.x targets.
+# Regenerates the auto-generated SDK API reference under
+# docs/next/api-reference/ from the SDK sources (TypeDoc for Node/Browser/
+# Helpers, griffe for Python, nightly rustdoc JSON for Rust). These pages are a
+# second, source-derived set that sits alongside the hand-authored
+# docs/next/sdk-reference/ pages; do not edit the generated files by hand.
+#
+# Runs on pushes to main that touch SDK sources or the generator, and on manual
+# dispatch. The commit is tagged [skip ci] so the push-back does not re-trigger.
 on:
+  push:
+    branches: [main]
+    paths:
+      - 'sdk/packages/node/iii/src/**'
+      - 'sdk/packages/node/iii-browser/src/**'
+      - 'sdk/packages/node/helpers/src/**'
+      - 'sdk/packages/python/iii/src/**'
+      - 'sdk/packages/python/helpers/src/**'
+      - 'sdk/packages/rust/iii/src/**'
+      - 'sdk/packages/rust/helpers/src/**'
+      - 'docs/next/scripts/**'
+      - 'sdk/packages/node/iii/typedoc.json'
+      - 'sdk/packages/node/iii-browser/typedoc.json'
+      - 'sdk/packages/node/helpers/typedoc.json'
   workflow_dispatch:
 
 concurrency:
@@ -40,38 +58,43 @@ jobs:
       - uses: dtolnay/rust-toolchain@stable
       - uses: dtolnay/rust-toolchain@nightly
 
-      # Step 1a: Extract Node SDK docs (TypeDoc)
+      # Step 1: Extract TypeDoc JSON (Node SDK, Browser SDK, Helpers)
       - name: Extract Node SDK docs
         run: pnpm --filter iii-sdk docs:json
-
-      # Step 1b: Extract Browser SDK docs (TypeDoc)
       - name: Extract Browser SDK docs
         run: pnpm --filter iii-browser-sdk docs:json
+      - name: Extract Helpers (Node) docs
+        run: pnpm --filter @iii-dev/helpers docs:json
 
-      # Step 2: Extract Python SDK docs (griffe)
+      # Step 2: Extract Python docs (griffe) for iii and iii_helpers
       - name: Extract Python SDK docs
         working-directory: sdk/packages/python/iii
         run: |
           uv sync --extra dev
-          uv run griffe dump iii -d google > api-docs.json
+          uv run --with griffe griffe dump iii -d google > api-docs.json
+      - name: Extract Python Helpers docs
+        working-directory: sdk/packages/python/helpers
+        run: |
+          uv sync
+          uv run --with griffe griffe dump iii_helpers -d google > api-docs.json
 
-      # Step 3: Extract Rust SDK docs (nightly rustdoc JSON)
+      # Step 3: Extract Rust docs (nightly rustdoc JSON) for both crates
       - name: Extract Rust SDK docs
         run: cargo +nightly rustdoc -p iii-sdk --all-features -- -Z unstable-options --output-format json
         continue-on-error: true
+      - name: Extract Rust Helpers docs
+        run: cargo +nightly rustdoc -p iii-helpers --all-features -- -Z unstable-options --output-format json
+        continue-on-error: true
 
-      # Step 4: Generate MDX from extracted JSON
+      # Step 4: Generate MDX from the extracted JSON
       - name: Generate MDX files
-        run: pnpm tsx docs/0-11-0/scripts/generate-api-docs.mts
+        run: pnpm tsx docs/next/scripts/generate-api-docs.mts
 
-      # Step 5: Commit if changed
+      # Step 5: Commit if changed (skip ci so the push-back doesn't loop)
       - name: Commit generated docs
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add docs/0-11-0/api-reference/sdk-node.mdx \
-                  docs/0-11-0/api-reference/sdk-browser.mdx \
-                  docs/0-11-0/api-reference/sdk-python.mdx \
-                  docs/0-11-0/api-reference/sdk-rust.mdx
-          git diff --cached --quiet || git commit -m "docs: regenerate SDK API reference"
+          git add docs/next/api-reference/*.mdx
+          git diff --cached --quiet || git commit -m "docs: regenerate SDK API reference [skip ci]"
           git push