diff --git a/aztec-up/bootstrap.sh b/aztec-up/bootstrap.sh
index a03a7409093a..120953b8ce76 100755
--- a/aztec-up/bootstrap.sh
+++ b/aztec-up/bootstrap.sh
@@ -17,6 +17,9 @@ function build {
   echo
 
   # Create Verdaccio config.
+  # publish.allow_offline lets verdaccio accept publishes when the npmjs
+  # uplink is briefly unreachable, instead of returning 503. We never want
+  # the upstream existence check to gate these local fake-publishes.
   cat > /tmp/verdaccio-config.yaml <<EOF
 storage: $PWD/verdaccio-storage
 max_body_size: 1000mb
@@ -25,6 +28,9 @@ uplinks:
   npmjs:
     url: https://registry.npmjs.org/
 
+publish:
+  allow_offline: true
+
 packages:
   "@*/*":
     access: \$all
diff --git a/docs/examples/ts/lib.sh b/docs/examples/ts/lib.sh
index 03039d94befa..886f7faba70d 100644
--- a/docs/examples/ts/lib.sh
+++ b/docs/examples/ts/lib.sh
@@ -7,10 +7,20 @@
 # Reads a config.yaml via yq and classifies each dependency entry into one of
 # three global arrays:
 #   AZTEC_DEPS          — @aztec/* packages resolved to pkg@link:<repo_root>/yarn-project/<name>
+#                         Exceptions (not published locally) are routed to NPM_DEPS:
+#                           - @aztec/viem (third-party fork pulled from npm)
 #   EXPLICIT_LINK_DEPS  — link: packages resolved to pkg@link:<repo_root>/<path>
 #   NPM_DEPS            — npm: packages (bare names, e.g. viem)
 #
 # Also sets PARSED_DEPS_FOUND to "true" if any dependency was found, "false" otherwise.
+
+# @aztec/* packages that live on npm rather than in yarn-project/.
+# When one of these appears bare (e.g. "@aztec/viem"), treat it as an npm dep
+# instead of trying to link it from yarn-project/<name>.
+AZTEC_NPM_EXCEPTIONS=(
+    "@aztec/viem"
+)
+
 parse_dependencies() {
     local config_file=$1
     local repo_root=$2
@@ -43,9 +53,23 @@ parse_dependencies() {
             local link_path="${link_spec#*:}"
             EXPLICIT_LINK_DEPS+=("${link_pkg_name}@link:${repo_root}/${link_path}")
         elif [[ "$pkg" =~ ^@ ]]; then
-            # @aztec/* package - auto-link from yarn-project/
-            local pkg_name="${pkg#@aztec/}"
-            AZTEC_DEPS+=("${pkg}@link:${repo_root}/yarn-project/${pkg_name}")
+            # Exception list: some @aztec/* packages live on npm, not in yarn-project/.
+            local is_npm_exception=false
+            local exc
+            for exc in "${AZTEC_NPM_EXCEPTIONS[@]}"; do
+                if [ "$pkg" = "$exc" ]; then
+                    is_npm_exception=true
+                    break
+                fi
+            done
+
+            if [ "$is_npm_exception" = true ]; then
+                NPM_DEPS+=("$pkg")
+            else
+                # @aztec/* package - auto-link from yarn-project/
+                local pkg_name="${pkg#@aztec/}"
+                AZTEC_DEPS+=("${pkg}@link:${repo_root}/yarn-project/${pkg_name}")
+            fi
         else
             echo "Warning: Unknown dependency format '$pkg' (use '@aztec/pkg', 'link:pkg:path', or 'npm:pkg')" >&2
         fi