diff --git a/.agents/skills/investigate/SKILL.md b/.agents/skills/investigate/SKILL.md
index fd67aeb4b..46ec0acc5 100644
--- a/.agents/skills/investigate/SKILL.md
+++ b/.agents/skills/investigate/SKILL.md
@@ -16,11 +16,11 @@ Investigate the following GitHub issue: $ARGUMENTS
 ### Phase 1: Fetch Issue Details
 
 1. Parse the input:
-   - `WDX-123` or `linear.app` URL → **Linear ticket**
+   - `DX-123` or `linear.app` URL → **Linear ticket**
    - `#123`, bare number, or `github.com` URL → **GitHub issue**
 2. Fetch the ticket:
    - **GitHub:** `gh issue view <number> --json title,body,labels,comments,author,createdAt,state`
-   - **Linear:** `bash .agents/skills/triage/scripts/linear-fetch.sh issue WDX-123`
+   - **Linear:** `bash .agents/skills/triage/scripts/linear-fetch.sh issue DX-123`
 3. Extract: error messages, stack traces, reproduction steps, environment details
 
 ### Phase 2: Identify Affected Package(s)
@@ -47,7 +47,7 @@ For each root cause: the fix (file paths + line numbers), test coverage needed,
 
 ## Output
 
-1. Extract identifier from arguments (issue `424` → `424`, ticket `WDX-296` → `WDX-296`, text → slugified)
+1. Extract identifier from arguments (issue `424` → `424`, ticket `DX-296` → `DX-296`, text → slugified)
 2. `mkdir -p claude-output`
 3. Write to `claude-output/investigate-<identifier>.md`
 4. Confirm to user: "Investigation written to `claude-output/investigate-<identifier>.md`"
diff --git a/.agents/skills/qa-engineer-manual/SKILL.md b/.agents/skills/qa-engineer-manual/SKILL.md
index 423c9ae5a..d221ceafd 100644
--- a/.agents/skills/qa-engineer-manual/SKILL.md
+++ b/.agents/skills/qa-engineer-manual/SKILL.md
@@ -34,6 +34,9 @@ You seed Storyblok QA spaces with predefined test scenarios. Packages might defi
 - Storyblok CLI built: `pnpm nx build storyblok`
 - `.env.qa-engineer-manual` file in repo root with `STORYBLOK_TOKEN` and `STORYBLOK_SPACE_ID`
 
+> [!NOTE]
+> The seed resolves the CLI and the `.storyblok` staging directory from `git rev-parse --show-toplevel`, i.e. the repo of your current working directory. To exercise changes in a worktree, build the CLI in that worktree and run the seed from inside it; otherwise it falls back to the main checkout's `dist`.
+
 ```bash
 # .env.qa-engineer-manual
 STORYBLOK_TOKEN=your_personal_access_token
@@ -103,6 +106,18 @@ bash .claude/skills/qa-engineer-manual/scripts/cleanup-remote.sh
 
 Deletes all stories, components (except the default `page` component), assets, asset folders, and internal tags in the space. Uses `STORYBLOK_SPACE_ID` from env by default (override with `--space <id>`). This runs automatically before every seed, but can also be used standalone.
 
+### Shared asset libraries
+
+Shared (org-level) asset libraries are global: they belong to the organization and can be shared across spaces, so a full wipe is destructive. Cleanup is scoped by folder membership, not by name. `--shared --library <libraryId>` deletes every shared asset in the library's folder tree, every internal tag scoped to the library, and every child folder. It never deletes the library root folder or any resource outside the given library. Folder scoping is deliberate: transferred assets keep their original names, so a `qa-` name prefix would miss them.
+
+Because this removes all content inside the library regardless of name, only run it against a dedicated QA library, never a shared library that holds real org content.
+
+```bash
+bash .claude/skills/qa-engineer-manual/scripts/cleanup-remote.sh --shared --library <libraryId>
+```
+
+Inspect a library first with `list.sh --resource shared-assets|shared-folders|shared-tags`. Package guides (for example `packages/cli/test/GUIDE.md`) describe the CLI push/pull workflow against libraries.
+
 ### Scenario structure
 
 A scenario is a directory with optional subdirectories for each resource type:
@@ -143,8 +158,8 @@ Paths are relative to this `SKILL.md`.
 | Script | Purpose |
 | --- | --- |
 | `./scripts/cleanup-local.sh` | Deletes local QA artifacts in `.storyblok/`. |
-| `./scripts/cleanup-remote.sh` | Deletes all stories, components (except `page`), assets, asset folders, and internal tags in the space. Accepts `--space <id>`. |
-| `./scripts/list.sh` | Lists resources in the QA space. Pass `--resource stories\|assets\|components\|datasources` and optionally `--space <id>`. |
+| `./scripts/cleanup-remote.sh` | Deletes all stories, components (except `page`), assets, asset folders, and internal tags in the space. Accepts `--space <id>`. Add `--shared --library <id>` to instead delete all shared resources in the given org library's folder tree, never the root (see "Shared asset libraries" below). |
+| `./scripts/list.sh` | Lists resources in the QA space. Pass `--resource stories\|assets\|components\|datasources` and optionally `--space <id>`. For org libraries: `--resource shared-assets\|shared-tags --library <id>` or `--resource shared-folders`. |
 | `./scripts/generate-story.sh` | Writes a story JSON to stdout. All fields optional — use flags to override `--slug`, `--name`, `--component`, `--parent-id`, `--is-folder`, `--id`, `--uuid`. |
 | `./scripts/generate-asset.sh` | Writes an asset sidecar JSON to stdout. Use `--filename`, `--alt`, `--title`, `--is-private`, `--folder-id`. Pass `--copy-png <path>` to also copy the template PNG to a target path. |
 
diff --git a/.agents/skills/qa-engineer-manual/scripts/_common.sh b/.agents/skills/qa-engineer-manual/scripts/_common.sh
index 3fd50bcd6..c7ae27b5c 100755
--- a/.agents/skills/qa-engineer-manual/scripts/_common.sh
+++ b/.agents/skills/qa-engineer-manual/scripts/_common.sh
@@ -5,6 +5,17 @@
 # Provides:
 #   load_env             — loads .env.qa-engineer-manual and asserts STORYBLOK_TOKEN
 #   require_space_id     — ensures space_id is set (from arg or env), exits if not
+#   require_library_id   — ensures library_id is set (from --library), exits if not
+#
+# Constants:
+#   QA_SHARED_PREFIX     — name prefix every QA-created shared resource must carry
+#                          so org-global libraries can be cleaned up safely
+#                          (only prefix-matched resources are ever deleted).
+
+# Shared asset libraries are org-global (shared across spaces), so a full wipe
+# is unsafe. Every QA-created shared asset, shared folder, and shared tag must
+# be named with this prefix; shared cleanup only deletes prefix-matched items.
+QA_SHARED_PREFIX="${QA_SHARED_PREFIX:-qa-}"
 
 # ---------------------------------------------------------------------------
 # load_env
@@ -53,3 +64,15 @@ require_space_id() {
     exit 1
   fi
 }
+
+# ---------------------------------------------------------------------------
+# require_library_id
+#   Call after parsing args. Ensures the global `library_id` variable is set
+#   (a top-level shared asset folder id). Exits with an error if not.
+# ---------------------------------------------------------------------------
+require_library_id() {
+  if [ -z "${library_id:-}" ]; then
+    printf "Missing --library <libraryId> (a top-level shared asset folder id).\n" >&2
+    exit 1
+  fi
+}
diff --git a/.agents/skills/qa-engineer-manual/scripts/cleanup-local.sh b/.agents/skills/qa-engineer-manual/scripts/cleanup-local.sh
index de63c813e..e78b22e30 100755
--- a/.agents/skills/qa-engineer-manual/scripts/cleanup-local.sh
+++ b/.agents/skills/qa-engineer-manual/scripts/cleanup-local.sh
@@ -28,6 +28,13 @@ for sid in "${space_ids[@]}"; do
   done
 done
 
+# Shared asset libraries live under .storyblok/assets/shared/<library_id>/,
+# keyed by org-global library ID rather than space ID, so clean the whole subtree.
+if [ -d ".storyblok/assets/shared" ]; then
+  rm -rf ".storyblok/assets/shared"
+  removed=$((removed + 1))
+fi
+
 if [ "${removed}" -eq 0 ]; then
   printf "clean\n"
 else
diff --git a/.agents/skills/qa-engineer-manual/scripts/cleanup-remote.sh b/.agents/skills/qa-engineer-manual/scripts/cleanup-remote.sh
index 2c342b830..cf027fcb4 100644
--- a/.agents/skills/qa-engineer-manual/scripts/cleanup-remote.sh
+++ b/.agents/skills/qa-engineer-manual/scripts/cleanup-remote.sh
@@ -5,6 +5,16 @@ set -euo pipefail
 #
 # Usage:
 #   bash .claude/skills/qa-engineer-manual/scripts/cleanup-remote.sh --space <spaceId>
+#
+# Shared (org-level) asset libraries are global, so a full wipe is unsafe.
+# --shared cleans every shared resource that belongs to ONE library, scoped by
+# folder membership (not by name): all assets in the library's folder tree, all
+# internal tags scoped to the library, and all child folders. Transferred assets
+# keep their original names, so folder scoping catches them where a name prefix
+# would not. It never deletes the library root folder (org context only) or any
+# resource outside the given library.
+#
+#   bash .claude/skills/qa-engineer-manual/scripts/cleanup-remote.sh --shared --library <libraryId>
 
 # shellcheck source=_common.sh
 source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"
@@ -14,6 +24,8 @@ load_env
 # Parse arguments
 # ---------------------------------------------------------------------------
 space_id=""
+shared_mode=false
+library_id=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -21,6 +33,14 @@ while [ "$#" -gt 0 ]; do
       space_id="$2"
       shift 2
       ;;
+    --shared)
+      shared_mode=true
+      shift 1
+      ;;
+    --library)
+      library_id="$2"
+      shift 2
+      ;;
     *)
       printf "warning: unknown argument '%s'\n" "$1" >&2
       shift 1
@@ -37,6 +57,144 @@ per_page=100
 found_total=0
 deleted_total=0
 
+# Deletes a list of ids (one per line) against an endpoint. Treats 2xx and 404
+# (already gone) as success. Runs in a command-substitution subshell, so it
+# keeps no global state: it prints "<found> <deleted>" for the caller to total.
+# Args: <delete_url_base> <label> <query_suffix> <ids>
+delete_ids() {
+  local url_base=$1
+  local label=$2
+  local query_suffix="${3:-}"
+  local ids=$4
+  local found_batch=0
+  local deleted_batch=0
+  while IFS= read -r id; do
+    [ -z "${id}" ] && continue
+    found_batch=$((found_batch + 1))
+    status=$(curl -s -o /dev/null -w "%{http_code}" --retry 3 --retry-delay 1 \
+      -X DELETE "${url_base}/${id}${query_suffix}" \
+      -H "Authorization: ${STORYBLOK_TOKEN}")
+    if [[ "${status}" == 2* || "${status}" == "404" ]]; then
+      deleted_batch=$((deleted_batch + 1))
+    else
+      printf "failed to delete %s/%s (status %s)\n" "${label}" "${id}" "${status}" >&2
+    fi
+  done <<< "${ids}"
+  printf '%s %s' "${found_batch}" "${deleted_batch}"
+}
+
+# ---------------------------------------------------------------------------
+# Shared (org-level) library cleanup — folder-scoped, never a full wipe
+# ---------------------------------------------------------------------------
+if [ "${shared_mode}" = true ]; then
+  require_library_id
+
+  folders_url="https://mapi.storyblok.com/v1/spaces/${space_id}/shared_asset_folders"
+  assets_url="https://mapi.storyblok.com/v1/spaces/${space_id}/shared_assets"
+  tags_url="https://mapi.storyblok.com/v1/spaces/${space_id}/shared_internal_tags"
+
+  # Resolve every folder id in the library's tree (root first, then children).
+  # Assets are scoped per folder, so the tree drives which assets get deleted.
+  folders_resp=$(curl -s --retry 3 --retry-delay 1 "${folders_url}/" \
+    -H "Authorization: ${STORYBLOK_TOKEN}")
+  tree_ids=$(printf '%s' "${folders_resp}" | node -e '
+    const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+    const library = parseInt(process.argv[1]);
+    const all = data.shared_asset_folders || [];
+    const parentById = new Map(all.map(f => [f.id, f.parent_id == null ? null : f.parent_id]));
+    const inLibrary = (id) => {
+      const seen = new Set();
+      let cur = id;
+      while (cur != null && !seen.has(cur)) {
+        if (cur === library) return true;
+        seen.add(cur);
+        cur = parentById.get(cur);
+      }
+      return false;
+    };
+    const ids = all.filter(f => f.id !== library && inLibrary(f.id)).map(f => f.id);
+    // Root first so its assets are enumerated even if the folder list is empty.
+    process.stdout.write([library, ...ids].join("\n"));
+  ' "${library_id}")
+
+  # 1. Shared assets in every folder of the library tree (no name filter),
+  #    paginated per folder.
+  while IFS= read -r folder; do
+    [ -z "${folder}" ] && continue
+    while true; do
+      assets_resp=$(curl -s --retry 3 --retry-delay 1 \
+        "${assets_url}/?in_folder=${folder}&page=1&per_page=${per_page}" \
+        -H "Authorization: ${STORYBLOK_TOKEN}")
+      asset_ids=$(printf '%s' "${assets_resp}" | node -e '
+        const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+        process.stdout.write((data.assets || []).map(a => a.id).join("\n"));
+      ')
+      [ -z "${asset_ids}" ] && break
+      read -r bf bd <<< "$(delete_ids "${assets_url}" "${folder}/shared_assets" "" "${asset_ids}")"
+      found_total=$((found_total + bf)); deleted_total=$((deleted_total + bd))
+      [ "${bd}" -eq 0 ] && break
+    done
+  done <<< "${tree_ids}"
+
+  # 2. Shared internal tags scoped to the library (no name filter), paginated
+  #    per pass: delete a page, then re-fetch page 1 until none remain.
+  while true; do
+    tags_resp=$(curl -s --retry 3 --retry-delay 1 \
+      "${tags_url}/?asset_folder_id=${library_id}&page=1&per_page=${per_page}" \
+      -H "Authorization: ${STORYBLOK_TOKEN}")
+    tag_ids=$(printf '%s' "${tags_resp}" | node -e '
+      const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+      process.stdout.write((data.internal_tags || []).map(t => t.id).join("\n"));
+    ')
+    [ -z "${tag_ids}" ] && break
+    read -r bf bd <<< "$(delete_ids "${tags_url}" "${library_id}/shared_internal_tags" "?asset_folder_id=${library_id}" "${tag_ids}")"
+    found_total=$((found_total + bf)); deleted_total=$((deleted_total + bd))
+    [ "${bd}" -eq 0 ] && break
+  done
+
+  # 3. Shared child folders in the library tree (never the root), deepest first
+  #    so leaf folders are removed before their parents.
+  while true; do
+    folders_resp=$(curl -s --retry 3 --retry-delay 1 "${folders_url}/" \
+      -H "Authorization: ${STORYBLOK_TOKEN}")
+    folder_ids=$(printf '%s' "${folders_resp}" | node -e '
+      const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
+      const library = parseInt(process.argv[1]);
+      const all = data.shared_asset_folders || [];
+      const parentById = new Map(all.map(f => [f.id, f.parent_id == null ? null : f.parent_id]));
+      const inLibrary = (id) => {
+        const seen = new Set();
+        let cur = id;
+        while (cur != null && !seen.has(cur)) {
+          if (cur === library) return true;
+          seen.add(cur);
+          cur = parentById.get(cur);
+        }
+        return false;
+      };
+      const items = all.filter(f =>
+        f.id !== library && f.parent_id != null && inLibrary(f.id),
+      );
+      // Deepest first: a child has more ancestors than its parent.
+      const depth = (id) => { let d = 0, cur = parentById.get(id), seen = new Set(); while (cur != null && !seen.has(cur)) { d++; seen.add(cur); cur = parentById.get(cur); } return d; };
+      items.sort((a, b) => depth(b.id) - depth(a.id));
+      process.stdout.write(items.map(f => f.id).join("\n"));
+    ' "${library_id}")
+    [ -z "${folder_ids}" ] && break
+    read -r bf bd <<< "$(delete_ids "${folders_url}" "${library_id}/shared_asset_folders" "" "${folder_ids}")"
+    found_total=$((found_total + bf)); deleted_total=$((deleted_total + bd))
+    [ "${bd}" -eq 0 ] && break
+  done
+
+  if [ "${found_total}" -eq 0 ]; then
+    printf "clean (no shared resources in library %s)\n" "${library_id}"
+  else
+    printf "deleted %s of %s shared resources in library %s\n" \
+      "${deleted_total}" "${found_total}" "${library_id}"
+  fi
+  exit 0
+fi
+
 cleanup_resource() {
   local resource=$1
   local skip_name="${2:-}"
diff --git a/.agents/skills/qa-engineer-manual/scripts/generate-asset.sh b/.agents/skills/qa-engineer-manual/scripts/generate-asset.sh
index b38d16a83..d053bcc1c 100644
--- a/.agents/skills/qa-engineer-manual/scripts/generate-asset.sh
+++ b/.agents/skills/qa-engineer-manual/scripts/generate-asset.sh
@@ -13,6 +13,13 @@ set -euo pipefail
 #   # To also copy the template PNG alongside:
 #   bash .claude/skills/qa-engineer-manual/scripts/generate-asset.sh \
 #     --filename "hero.png" --copy-png scenarios/my-scenario/assets/hero.png > scenarios/my-scenario/assets/hero.json
+#
+# For shared (org library) assets, keep the default `qa-` filename prefix so
+# cleanup-remote.sh --shared can find them, and point --folder-id at the
+# library (or a child folder):
+#   bash .claude/skills/qa-engineer-manual/scripts/generate-asset.sh \
+#     --filename "qa-hero.png" --folder-id <libraryId> \
+#     --copy-png .storyblok/assets/shared/<libraryId>/qa-hero.png > .storyblok/assets/shared/<libraryId>/qa-hero.json
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 template_png="${SCRIPT_DIR}/../templates/asset-template.png"
diff --git a/.agents/skills/qa-engineer-manual/scripts/list.sh b/.agents/skills/qa-engineer-manual/scripts/list.sh
index 7bc04651d..64c9674db 100755
--- a/.agents/skills/qa-engineer-manual/scripts/list.sh
+++ b/.agents/skills/qa-engineer-manual/scripts/list.sh
@@ -8,6 +8,12 @@ set -euo pipefail
 #   bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource assets --space <spaceId>
 #   bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource components
 #   bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource datasources
+#
+# Shared (org-level) asset libraries — require --library <libraryId> for the
+# asset/tag listings (a top-level shared asset folder id):
+#   bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource shared-assets --library <libraryId>
+#   bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource shared-folders
+#   bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource shared-tags --library <libraryId>
 
 # shellcheck source=_common.sh
 source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"
@@ -18,11 +24,13 @@ load_env
 # ---------------------------------------------------------------------------
 space_id=""
 resource=""
+library_id=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --space)    space_id="$2"; shift 2 ;;
     --resource) resource="$2"; shift 2 ;;
+    --library)  library_id="$2"; shift 2 ;;
     *)          printf "warning: unknown argument '%s'\n" "$1" >&2; shift 1 ;;
   esac
 done
@@ -30,16 +38,17 @@ done
 require_space_id
 
 if [ -z "${resource}" ]; then
-  printf "Missing --resource <stories|assets|components|datasources>.\n" >&2
+  printf "Missing --resource <stories|assets|components|datasources|shared-assets|shared-folders|shared-tags>.\n" >&2
   exit 1
 fi
 
 # ---------------------------------------------------------------------------
 # Per-resource formatters (inline Node.js)
 # ---------------------------------------------------------------------------
-# Each formatter prints rows to stdout, then a final line: __COUNT__<n>
+# Each formatter receives the response `data` and a `key` (the array property),
+# prints rows to stdout, then a final line: __COUNT__<n>
 format_stories='
-  const items = data.stories || [];
+  const items = data[key] || [];
   items.forEach(s =>
     process.stdout.write(s.id + "\t" + s.slug + "\t" + (s.published ? "published" : "draft") + "\n")
   );
@@ -47,9 +56,9 @@ format_stories='
 '
 
 format_assets='
-  const items = data.assets || [];
+  const items = data[key] || [];
   items.forEach(a => {
-    const name = (a.filename || "").split("/").pop();
+    const name = (a.short_filename || (a.filename || "").split("/").pop());
     const folder = a.asset_folder_id || "-";
     process.stdout.write(a.id + "\t" + name + "\t" + folder + "\n");
   });
@@ -57,7 +66,7 @@ format_assets='
 '
 
 format_components='
-  const items = data.components || [];
+  const items = data[key] || [];
   items.forEach(c => {
     const root = c.is_root ? "root" : "-";
     const nestable = c.is_nestable ? "nestable" : "-";
@@ -67,7 +76,7 @@ format_components='
 '
 
 format_datasources='
-  const items = data.datasources || [];
+  const items = data[key] || [];
   items.forEach(d => {
     const dims = (d.dimensions || []).length;
     process.stdout.write(d.id + "\t" + d.slug + "\t" + d.name + "\t" + dims + " dims\n");
@@ -75,13 +84,37 @@ format_datasources='
   process.stdout.write("__COUNT__" + items.length + "\n");
 '
 
+format_shared_folders='
+  const items = data[key] || [];
+  const lib = libArg ? parseInt(libArg) : undefined;
+  items
+    .filter(f => lib === undefined || f.id === lib || f.parent_id === lib)
+    .forEach(f => {
+      const parent = f.parent_id == null ? "root" : f.parent_id;
+      const access = (f.asset_folder_access || []).map(a => a.space_id + ":" + a.access_level).join(",") || "-";
+      process.stdout.write(f.id + "\t" + f.name + "\t" + parent + "\t" + access + "\n");
+    });
+  process.stdout.write("__COUNT__" + items.length + "\n");
+'
+
+format_shared_tags='
+  const items = data[key] || [];
+  items.forEach(t => process.stdout.write(t.id + "\t" + t.name + "\n"));
+  process.stdout.write("__COUNT__" + items.length + "\n");
+'
+
+# Resolve resource → path segment, response key, formatter, extra query string.
+extra_query=""
 case "${resource}" in
-  stories)     format_js="${format_stories}" ;;
-  assets)      format_js="${format_assets}" ;;
-  components)  format_js="${format_components}" ;;
-  datasources) format_js="${format_datasources}" ;;
+  stories)       path_segment="stories";              response_key="stories";              format_js="${format_stories}" ;;
+  assets)        path_segment="assets";               response_key="assets";               format_js="${format_assets}" ;;
+  components)    path_segment="components";           response_key="components";           format_js="${format_components}" ;;
+  datasources)   path_segment="datasources";          response_key="datasources";          format_js="${format_datasources}" ;;
+  shared-assets) require_library_id; path_segment="shared_assets";        response_key="assets";        format_js="${format_assets}";        extra_query="&in_folder=${library_id}" ;;
+  shared-folders) path_segment="shared_asset_folders"; response_key="shared_asset_folders"; format_js="${format_shared_folders}" ;;
+  shared-tags)   require_library_id; path_segment="shared_internal_tags"; response_key="internal_tags"; format_js="${format_shared_tags}";   extra_query="&asset_folder_id=${library_id}" ;;
   *)
-    printf "Unknown resource '%s'. Use stories, assets, components, or datasources.\n" "${resource}" >&2
+    printf "Unknown resource '%s'. Use stories, assets, components, datasources, shared-assets, shared-folders, or shared-tags.\n" "${resource}" >&2
     exit 1
     ;;
 esac
@@ -95,13 +128,15 @@ total=0
 
 while true; do
   response=$(curl -s --retry 3 --retry-delay 1 \
-    "https://mapi.storyblok.com/v1/spaces/${space_id}/${resource}/?page=${page}&per_page=${per_page}" \
+    "https://mapi.storyblok.com/v1/spaces/${space_id}/${path_segment}/?page=${page}&per_page=${per_page}${extra_query}" \
     -H "Authorization: ${STORYBLOK_TOKEN}")
 
   output=$(printf '%s' "${response}" | node -e "
     const data = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+    const libArg = process.argv[1];
+    const key = process.argv[2];
     ${format_js}
-  ")
+  " "${library_id}" "${response_key}")
 
   # Last line is __COUNT__<n>; everything before it is row output
   batch="${output##*__COUNT__}"
diff --git a/.agents/skills/qa-engineer-manual/scripts/seed-scenario.sh b/.agents/skills/qa-engineer-manual/scripts/seed-scenario.sh
index 2c97e570a..2f2a37534 100644
--- a/.agents/skills/qa-engineer-manual/scripts/seed-scenario.sh
+++ b/.agents/skills/qa-engineer-manual/scripts/seed-scenario.sh
@@ -272,7 +272,9 @@ fi
 
 # 3. Assets (must precede stories)
 if [ "${skip_assets}" = false ] && [ -d "${staging_dir}/assets/${FAKE_ID}" ]; then
-  run_push "assets" node "${cli_bin}" assets push --from "${FAKE_ID}" --space "${space_id}"
+  # Seeding is space-scoped: never push to org shared libraries (bulk push
+  # otherwise defaults to --target=all and scans accessible libraries).
+  run_push "assets" node "${cli_bin}" assets push --from "${FAKE_ID}" --space "${space_id}" --target space
 fi
 
 # 4. Stories (reads asset manifest.jsonl for ID remapping automatically)
diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md
index 0ad7a5ec4..6b977e8cc 100644
--- a/.agents/skills/spec/SKILL.md
+++ b/.agents/skills/spec/SKILL.md
@@ -15,7 +15,7 @@ Generate a spec for: $ARGUMENTS
 **IMPORTANT:** Write the spec output to a markdown file, NOT to the terminal.
 
 1. Extract an identifier from the arguments:
-   - For ticket IDs like `WDX-237` -> use `wdx-237`
+   - For ticket IDs like `DX-237` -> use `dx-237`
    - For descriptions -> slugify the first few words (e.g., "CLI login flow" -> `cli-login-flow`)
 
 2. Create the output directory if it doesn't exist:
diff --git a/.agents/skills/triage/SKILL.md b/.agents/skills/triage/SKILL.md
index e6aa5037f..00dd20b37 100644
--- a/.agents/skills/triage/SKILL.md
+++ b/.agents/skills/triage/SKILL.md
@@ -18,9 +18,9 @@ Read the ticket thoroughly, but do not dig into code. The goal is to classify, p
 
 ### Step 1: Parse ticket references
 
-- Anything matching `WDX-\d+` or a `linear.app` URL → **Linear**
+- Anything matching `DX-\d+` or a `linear.app` URL → **Linear**
 - Anything matching `#\d+`, a bare number, or a `github.com` URL → **GitHub**
-- `linear:triage` → fetch all Linear issues in Triage state (WDX team)
+- `linear:triage` → fetch all Linear issues in Triage state (DX team)
 
 ### Step 2: Fetch tickets
 
@@ -31,7 +31,7 @@ gh issue view <number> --repo storyblok/monoblok --json title,body,labels,state,
 
 **Linear:**
 ```bash
-bash .claude/skills/triage/scripts/linear-fetch.sh issue WDX-123 WDX-456
+bash .claude/skills/triage/scripts/linear-fetch.sh issue DX-123 DX-456
 bash .claude/skills/triage/scripts/linear-fetch.sh triage
 ```
 
@@ -113,7 +113,7 @@ If exact duplicate → mark as **duplicate** with link to original. If related b
 | Ticket | Title | Type | Priority | Verdict | Package |
 |--------|-------|------|----------|---------|---------|
 | #368 | ... | bug | P1 | actionable | cli |
-| WDX-123 | ... | improvement | P2 | actionable | vue |
+| DX-123 | ... | improvement | P2 | actionable | vue |
 ```
 
 #### Detailed assessment (one per ticket)
diff --git a/.agents/skills/triage/scripts/linear-fetch.sh b/.agents/skills/triage/scripts/linear-fetch.sh
index 724a7ce71..a26184773 100755
--- a/.agents/skills/triage/scripts/linear-fetch.sh
+++ b/.agents/skills/triage/scripts/linear-fetch.sh
@@ -2,9 +2,9 @@
 # Fetch Linear issues for triage.
 #
 # Usage:
-#   linear-fetch.sh issue WDX-123          # Single issue by identifier
-#   linear-fetch.sh issue WDX-123 WDX-456  # Multiple issues
-#   linear-fetch.sh triage                  # Triage issues for WDX team (default)
+#   linear-fetch.sh issue DX-123          # Single issue by identifier
+#   linear-fetch.sh issue DX-123 DX-456  # Multiple issues
+#   linear-fetch.sh triage                  # Triage issues for DX team (default)
 #   linear-fetch.sh triage --team OTHER    # Triage issues for a different team
 #
 # Requires LINEAR_API_KEY in the project .env file.
@@ -14,7 +14,7 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
 LINEAR_API="https://api.linear.app/graphql"
-DEFAULT_TEAM="WDX"
+DEFAULT_TEAM="DX"
 
 # ---------------------------------------------------------------------------
 # load_env — loads LINEAR_API_KEY from .env
@@ -47,7 +47,7 @@ gql() {
 }
 
 # ---------------------------------------------------------------------------
-# fetch_issue — fetch a single issue by identifier (e.g. WDX-123)
+# fetch_issue — fetch a single issue by identifier (e.g. DX-123)
 # ---------------------------------------------------------------------------
 fetch_issue() {
   local identifier="$1"
@@ -77,7 +77,7 @@ fetch_issue() {
     }
   '
 
-  # Extract team key and number from identifier (e.g. WDX-123)
+  # Extract team key and number from identifier (e.g. DX-123)
   local team_key="${identifier%%-*}"
   local number="${identifier##*-}"
 
@@ -150,7 +150,7 @@ shift || true
 case "$command" in
   issue)
     if [ $# -eq 0 ]; then
-      echo "Usage: linear-fetch.sh issue WDX-123 [WDX-456 ...]" >&2
+      echo "Usage: linear-fetch.sh issue DX-123 [DX-456 ...]" >&2
       exit 1
     fi
     # Fetch each issue and collect results
@@ -166,8 +166,8 @@ case "$command" in
     echo "Usage: linear-fetch.sh <issue|triage> [args...]" >&2
     echo ""
     echo "Commands:"
-    echo "  issue WDX-123 [WDX-456 ...]   Fetch specific issues by identifier"
-    echo "  triage [--team WDX]            Fetch all issues in Triage state"
+    echo "  issue DX-123 [DX-456 ...]   Fetch specific issues by identifier"
+    echo "  triage [--team DX]            Fetch all issues in Triage state"
     exit 1
     ;;
 esac
diff --git a/.claude/rules/artifact-naming.md b/.claude/rules/artifact-naming.md
index 08720e6a2..e5836092f 100644
--- a/.claude/rules/artifact-naming.md
+++ b/.claude/rules/artifact-naming.md
@@ -14,15 +14,15 @@ claude-output/<type>-<identifier>-<subtype>.md
 | Command | Pattern | Example |
 |---------|---------|---------|
 | `/review-and-qa` | `review-<id>.md` | `review-pr-435.md`, `review-login-flow.md` |
-| `/investigate` | `investigate-<id>.md` | `investigate-424.md`, `investigate-WDX-296.md` |
-| `/spec` (project) | `spec-<id>.md` | `spec-wdx-310.md`, `spec-asset-optimization.md` |
-| `/spec` (ticket) | `ticket-<id>.md` | `ticket-wdx-237.md`, `ticket-add-logout-button.md` |
-| PR description | `pr-<id>-summary.md` | `pr-435-summary.md`, `pr-WDX-308-summary.md` |
+| `/investigate` | `investigate-<id>.md` | `investigate-424.md`, `investigate-DX-296.md` |
+| `/spec` (project) | `spec-<id>.md` | `spec-dx-310.md`, `spec-asset-optimization.md` |
+| `/spec` (ticket) | `ticket-<id>.md` | `ticket-dx-237.md`, `ticket-add-logout-button.md` |
+| PR description | `pr-<id>-summary.md` | `pr-435-summary.md`, `pr-DX-308-summary.md` |
 
 ## Identifier extraction
 
 - PR URL `https://github.com/.../pull/435` or `#435` -> `435`
-- Ticket ID `WDX-308` -> `WDX-308`
+- Ticket ID `DX-308` -> `DX-308`
 - Free text "add logout button" -> `add-logout-button` (slugified)
 
 When the same PR/issue produces multiple artifacts (summary + review), the identifier stays the same and the type differentiates them: `pr-435-summary.md`, `review-pr-435.md`.
diff --git a/AGENTS.md b/AGENTS.md
index 7f08932ab..63d42c228 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,8 +45,8 @@ When a significant architectural decision is made, add a concise new ADR in `adr
 
 - **IMPORTANT:** Never stage or commit any code yourself unless explicitly told so!
 - **IMPORTANT:** Never use `git push --force`; if a force push is explicitly required, use `git push --force-with-lease` instead.
-- **Branch naming:** `[fix|feat|chore]/WDX-XXX-[title]` e.g. `feat/WDX-351-type-safe-schema-support`, `fix/WDX-391-push-stories-missing-story-identification`, or `chore/update-eslint-config`.
-- **Commits:** If information is available, add `Fixes WDX-*` and `Fixes #*` as footer lines at the end of commit messages for Linear and GitHub tracking.
+- **Branch naming:** `[fix|feat|chore]/DX-XXX-[title]` e.g. `feat/DX-351-type-safe-schema-support`, `fix/DX-391-push-stories-missing-story-identification`, or `chore/update-eslint-config`.
+- **Commits:** If information is available, add `Fixes DX-*` and `Fixes #*` as footer lines at the end of commit messages for Linear and GitHub tracking.
 
 **Worktrees:**
 
diff --git a/adr/0004-openapi-specs-pulled-on-demand.md b/adr/0004-openapi-specs-pulled-on-demand.md
index 2cebfb5f2..94646df57 100644
--- a/adr/0004-openapi-specs-pulled-on-demand.md
+++ b/adr/0004-openapi-specs-pulled-on-demand.md
@@ -10,7 +10,7 @@ Several packages generate their public types (and, for the API clients, SDK code
 Two pressures motivated a change:
 
 - The hand-written spec is a second source of truth that can drift from the backend, and the plan is to stop shipping any OpenAPI spec as a public artifact in the monorepo. The authoritative, overlay-applied specs live in a private repository (`storyblok/openapi-wdx`) that external contributors cannot access, yet the monorepo must stay buildable by them.
-- A single shared types package coupled unrelated consumers: any spec change bumped the shared package, cascading version bumps to every dependent regardless of whether its slice of the surface actually changed (WDX-430).
+- A single shared types package coupled unrelated consumers: any spec change bumped the shared package, cascading version bumps to every dependent regardless of whether its slice of the surface actually changed (DX-430).
 
 ## Decision
 
@@ -30,4 +30,4 @@ Key choices:
 - Version bumps are scoped per consumer, never driven by a shared types package or by the codegen tool.
 - Spec updates require a manual fetch, regeneration, and commit by someone with access. CI cannot do it.
 
-Links: WDX-406, WDX-430.
+Links: DX-406, DX-430.
diff --git a/adr/0005-components-selective-pull-dependency-semantics.md b/adr/0005-components-selective-pull-dependency-semantics.md
new file mode 100644
index 000000000..af154cb66
--- /dev/null
+++ b/adr/0005-components-selective-pull-dependency-semantics.md
@@ -0,0 +1,44 @@
+# ADR-0005: Components Selective Pull and Push Dependency Semantics
+
+**Status:** Accepted
+**Date:** 2026-07-07
+
+## Context
+
+Teams that share a single Storyblok space often only want to sync the components they own, not the entire schema. `components pull` gained `--filter <glob>`, `--group <name|Parent/Child path>` (repeatable, and includes descendant groups), and `--tag <name>` (repeatable and comma-separated), and `components push` gained the matching `--group` and `--tag` selectors alongside its existing `--filter`. Selectors combine with AND across different selector types and OR within a repeatable selector's values.
+
+Selecting a subset of components raises a dependency question: when a component is selected, which of its related records (groups, tags, presets, and other components referenced from its schema) should be pulled or pushed alongside it? Components can reference groups and tags by ID (as their assigned group and tags) and can also reference groups and tags from inside field-level whitelists (`component_group_whitelist`, `component_tag_whitelist`), and they can reference other components by name through `component_whitelist`.
+
+## Options considered
+
+- **Option A (chosen): matches plus their own direct dependencies, minus sibling components.** A selected set includes the matched components, their assigned groups (with ancestors), assigned tags, presets, and the groups (with ancestors) and tags referenced by their own schema whitelists. It does not follow `component_whitelist` to pull in sibling components.
+- **Option B: matches plus their full transitive dependencies, including sibling components.** This extends option A by following each matched component's `component_whitelist` to its sibling components, then collecting those siblings' dependencies too, recursively. It is the behavior `push --filter` had before this change. Rejected: `component_whitelist` is name-based and self-heals, so siblings are not required for a valid push, and following it silently expands a selection outward until it can reach most of the space, which defeats the point of a team syncing only the components it owns.
+- **Option C: literal matches only, no dependencies.** Only the matched components, with no groups, tags, or presets. Rejected: group and tag references are ID-based and cannot self-heal, so a cross-space push of a component without its group and tag records leaves those references dangling, and a nested group whose ancestors are absent is rejected by the backend with a 422.
+
+## Decision
+
+### Dependency semantics
+
+A selected set of components includes:
+
+- The matched components themselves.
+- Their assigned groups, including all ancestor groups up to the root.
+- Their assigned tags.
+- Their presets.
+- The groups (with ancestors) and tags referenced by their own schema whitelists.
+
+Sibling components referenced through a `component_whitelist` field are not pulled or pushed as part of the selection.
+
+Rationale: group and tag references are ID-based. The target space assigns its own IDs, so a cross-space push must remap the referenced group or tag ID, which requires the group or tag record to be present in the pushed payload. The backend also rejects a component whose group has a `parent_id` pointing at a group that does not exist in the target space with a 422, so ancestor groups must travel with their descendants. `component_whitelist`, by contrast, is name-based: it needs no ID remapping, and if the referenced component is missing in the target space at push time, the whitelist entry simply does not match anything until that component is pushed too. Excluding sibling components from selection keeps a selective pull or push focused on the components a team actually owns, instead of silently pulling in every other component reachable through whitelists.
+
+### Client-side filtering over server-side query parameters
+
+Selectors filter the full fetched or loaded component set in memory, rather than requesting a pre-filtered set from the API through `in_group` or `with_tags` query parameters. The dependency collector needs to see the complete component, group, and tag data to trace which groups, tags, and ancestors a matched component depends on. Filtering server-side would return only the matched components and leave the collector without the data it needs to resolve dependencies correctly.
+
+## Consequences
+
+- `pull` and `push` selectors are symmetric: the same `--filter`, `--group`, and `--tag` flags mean the same thing on both commands.
+- `push --filter` no longer expands to include sibling components referenced via `component_whitelist`; previously matched components pulled in their whitelisted siblings implicitly, and that behavior is now scoped to the option A dependency set.
+- A cross-space push of a selected slice can leave harmless dangling `component_whitelist` names that reference components not yet present in the target space. These self-heal once the referenced components are pushed, since the whitelist match is name-based and requires no remapping.
+- Pull and push always fetch or load the full component, group, and tag data before filtering, so selective sync does not reduce the amount of data read from disk or from the API; it only reduces what gets written or uploaded.
+- The single-component `push <componentName>` path also no longer carries whitelisted sibling components through `component_whitelist`, for the same option A rationale: name-based references self-heal once the referenced component is pushed.
diff --git a/commitlint.config.js b/commitlint.config.js
index 4d1a27e22..fff592f07 100644
--- a/commitlint.config.js
+++ b/commitlint.config.js
@@ -1,6 +1,30 @@
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Commit scopes derived from the folders under `packages/`, so the list stays
+// in sync automatically as packages are added or removed.
+const packagesDir = join(dirname(fileURLToPath(import.meta.url)), 'packages');
+const packageScopes = readdirSync(packagesDir, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory())
+  .map((entry) => entry.name)
+  .sort();
+
+// Scopes for changes that don't belong to a single package (root config,
+// tooling, CI, docs, agent skills, automated releases). These are intentionally
+// NOT packages, so such commits bump no package version.
+const metaScopes = ['release', 'repo', 'deps', 'ci', 'docs', 'tools', 'agents'];
+
 export default {
   extends: ['@commitlint/config-conventional'],
   rules: {
     'body-max-line-length': [2, 'always', 200],
+    // A scope is mandatory. Nx attributes an *unscoped* commit that touches
+    // non-project files (e.g. `.agents/`, root config) to EVERY package, which
+    // bumps the version of packages that had no actual change. Requiring a
+    // scope prevents that accidental workspace-wide fan-out.
+    'scope-empty': [2, 'never'],
+    // Comma-separated scopes are allowed, e.g. `feat(cli,mapi-client): ...`.
+    'scope-enum': [2, 'always', [...packageScopes, ...metaScopes]],
   },
 };
diff --git a/packages/angular/README.md b/packages/angular/README.md
index 74f2f6b56..0aad47dae 100644
--- a/packages/angular/README.md
+++ b/packages/angular/README.md
@@ -58,11 +58,7 @@ Add the Storyblok provider to your application configuration:
 ```typescript
 // app.config.ts
 import { ApplicationConfig } from '@angular/core';
-import {
-  provideStoryblok,
-  withStoryblokComponents,
-  withLivePreview,
-} from '@storyblok/angular';
+import { provideStoryblok, withStoryblokComponents, withLivePreview } from '@storyblok/angular';
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -75,7 +71,7 @@ export const appConfig: ApplicationConfig = {
         page: () => import('./components/page').then((m) => m.PageComponent),
         teaser: () => import('./components/teaser').then((m) => m.TeaserComponent),
       }),
-      withLivePreview()
+      withLivePreview(),
     ),
   ],
 };
@@ -143,8 +139,8 @@ provideStoryblok(
   { accessToken: 'YOUR_ACCESS_TOKEN' },
   withLivePreview({
     resolveRelations: ['article.author'],
-  })
-)
+  }),
+);
 ```
 
 In your route component, listen for live updates:
@@ -159,7 +155,7 @@ import { LivePreviewService, SbBlokDirective, type ISbStoryData } from '@storybl
 })
 export class CatchAllComponent implements OnInit {
   private readonly livePreview = inject(LivePreviewService);
-  
+
   readonly storyInput = input<ISbStoryData | null>(null, { alias: 'story' });
   readonly story = linkedSignal(() => this.storyInput());
 
@@ -177,14 +173,14 @@ Use the `SbRichTextComponent` to render rich text fields:
 
 ```typescript
 import { Component, input } from '@angular/core';
-import { SbRichTextComponent, type StoryblokRichTextNode } from '@storyblok/angular';
+import { SbRichTextComponent, type SbRichTextNode } from '@storyblok/angular';
 
 @Component({
   imports: [SbRichTextComponent],
   template: `<sb-rich-text [doc]="content()" />`,
 })
 export class ArticleComponent {
-  readonly content = input<StoryblokRichTextNode>();
+  readonly content = input<SbRichTextNode>();
 }
 ```
 
@@ -201,35 +197,30 @@ provideStoryblok(
   withStoryblokRichtextComponents({
     link: CustomLinkComponent,
     image: OptimizedImageComponent,
-  })
-)
+  }),
+);
 ```
 
 Create a custom component using the `props` input pattern:
 
 ```typescript
-import { Component, input, computed } from '@angular/core';
-import { SbRichTextNodeComponent, type AngularRenderNode } from '@storyblok/angular';
-
-interface LinkProps {
-  href?: string;
-  target?: string;
-  children?: AngularRenderNode[];
-}
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import type { SbAngularRichTextProps } from '@storyblok/angular';
 
 @Component({
-  imports: [SbRichTextNodeComponent],
+  selector: 'app-link',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
-    <a [href]="href()" [target]="target()" class="custom-link">
-      <sb-rich-text-node [nodes]="children()" />
+    <a [href]="data().attrs?.href">
+      <ng-content />
     </a>
   `,
+  host: {
+    style: 'display: inline-block',
+  },
 })
-export class CustomLinkComponent {
-  readonly props = input<LinkProps>({});
-  readonly href = computed(() => this.props().href ?? '');
-  readonly target = computed(() => this.props().target ?? '_self');
-  readonly children = computed(() => this.props().children ?? []);
+export class LinkComponent {
+  readonly data = input.required<SbAngularRichTextProps<'link'>>();
 }
 ```
 
@@ -246,44 +237,44 @@ const storyblokComponents: StoryblokComponentsMap = {
 
 provideStoryblok(
   { accessToken: 'YOUR_ACCESS_TOKEN' },
-  withStoryblokComponents(storyblokComponents)
-)
+  withStoryblokComponents(storyblokComponents),
+);
 ```
 
 ## API reference
 
 ### Providers
 
-| Provider | Description |
-|----------|-------------|
+| Provider                                | Description                                               |
+| --------------------------------------- | --------------------------------------------------------- |
 | `provideStoryblok(config, ...features)` | Configure the SDK with access token and optional features |
-| `withStoryblokComponents(map)` | Register Storyblok components (eager or lazy) |
-| `withLivePreview(options?)` | Enable real-time visual editing |
-| `withStoryblokRichtextComponents(map)` | Register custom rich text components |
+| `withStoryblokComponents(map)`          | Register Storyblok components (eager or lazy)             |
+| `withLivePreview(options?)`             | Enable real-time visual editing                           |
+| `withStoryblokRichtextComponents(map)`  | Register custom rich text components                      |
 
 ### Services
 
-| Service | Description |
-|---------|-------------|
-| `StoryblokService` | Access the Storyblok API client |
+| Service              | Description                     |
+| -------------------- | ------------------------------- |
+| `StoryblokService`   | Access the Storyblok API client |
 | `LivePreviewService` | Listen for live preview updates |
 
 ### Components and directives
 
-| Component/Directive | Description |
-|---------------------|-------------|
-| `SbBlokDirective` | Dynamically render Storyblok components |
-| `SbRichTextComponent` | Render rich text content |
+| Component/Directive       | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+| `SbBlokDirective`         | Dynamically render Storyblok components        |
+| `SbRichTextComponent`     | Render rich text content                       |
 | `SbRichTextNodeComponent` | Render rich text nodes (for custom components) |
 
 ### Types
 
-| Type | Description |
-|------|-------------|
-| `SbBlokData` | Base type for Storyblok block data |
-| `ISbStoryData` | Story data from the API |
-| `StoryblokRichTextNode` | Rich text document node |
-| `AngularRenderNode` | Rendered node in rich text AST |
+| Type                | Description                        |
+| ------------------- | ---------------------------------- |
+| `SbBlokData`        | Base type for Storyblok block data |
+| `ISbStoryData`      | Story data from the API            |
+| `SbRichTextNode`    | Rich text document node            |
+| `AngularRenderNode` | Rendered node in rich text AST     |
 
 ## Documentation
 
diff --git a/packages/angular/TUTORIAL.md b/packages/angular/TUTORIAL.md
deleted file mode 100644
index 6ef8682f9..000000000
--- a/packages/angular/TUTORIAL.md
+++ /dev/null
@@ -1,650 +0,0 @@
-# Build a website with Angular and Storyblok
-
-This tutorial walks you through building a content-driven website using Angular and Storyblok. You will learn how to fetch content, create dynamic components, enable live editing, and render rich text.
-
-## Prerequisites
-
-- Node.js 18 or later
-- Angular CLI (`npm install -g @angular/cli`)
-- A [Storyblok account](https://app.storyblok.com/#!/signup)
-
-## Create a new Angular project
-
-Create a new Angular project with SSR support:
-
-```bash
-ng new my-storyblok-app --ssr
-cd my-storyblok-app
-```
-
-Install the Storyblok Angular SDK:
-
-```bash
-npm install @storyblok/angular
-```
-
-## Configure Storyblok
-
-### Get your access token
-
-1. Log in to your Storyblok space
-2. Go to **Settings** > **Access Tokens**
-3. Copy your **Preview** access token
-
-### Set up the provider
-
-Update your `app.config.ts` to configure the SDK:
-
-```typescript
-// src/app/app.config.ts
-import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
-import { provideRouter } from '@angular/router';
-import { provideClientHydration, withEventReplay } from '@angular/platform-browser';
-import {
-  provideStoryblok,
-  withStoryblokComponents,
-  withLivePreview,
-} from '@storyblok/angular';
-import { routes } from './app.routes';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideBrowserGlobalErrorListeners(),
-    provideRouter(routes),
-    provideClientHydration(withEventReplay()),
-    provideStoryblok(
-      {
-        accessToken: 'YOUR_ACCESS_TOKEN',
-        region: 'eu', // Change based on your space region
-      },
-      withStoryblokComponents({
-        // Components will be added here
-      }),
-      withLivePreview()
-    ),
-  ],
-};
-```
-
-## Create Storyblok components
-
-Create a folder structure for your Storyblok components:
-
-```
-src/app/
-├── components/
-│   ├── page/
-│   │   └── page.component.ts
-│   ├── teaser/
-│   │   └── teaser.component.ts
-│   ├── grid/
-│   │   └── grid.component.ts
-│   └── feature/
-│       └── feature.component.ts
-└── storyblok.components.ts
-```
-
-### Page component
-
-The page component serves as a container for other components:
-
-```typescript
-// src/app/components/page/page.component.ts
-import { Component, ChangeDetectionStrategy, input } from '@angular/core';
-import { SbBlokDirective, type SbBlokData } from '@storyblok/angular';
-
-export interface PageBlok extends SbBlokData {
-  body?: SbBlokData[];
-}
-
-@Component({
-  selector: 'app-page',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [SbBlokDirective],
-  template: `
-    <div class="page">
-      @for (blok of blok().body ?? []; track blok._uid) {
-        <ng-container [sbBlok]="blok" />
-      }
-    </div>
-  `,
-})
-export class PageComponent {
-  readonly blok = input.required<PageBlok>();
-}
-```
-
-### Teaser component
-
-A simple teaser component with a headline:
-
-```typescript
-// src/app/components/teaser/teaser.component.ts
-import { Component, ChangeDetectionStrategy, input } from '@angular/core';
-import { type SbBlokData } from '@storyblok/angular';
-
-export interface TeaserBlok extends SbBlokData {
-  headline?: string;
-}
-
-@Component({
-  selector: 'app-teaser',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  template: `
-    <div class="teaser">
-      <h1>{{ blok().headline }}</h1>
-    </div>
-  `,
-  styles: `
-    .teaser {
-      padding: 2rem;
-      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-      color: white;
-      text-align: center;
-      border-radius: 8px;
-      margin-bottom: 2rem;
-    }
-  `,
-})
-export class TeaserComponent {
-  readonly blok = input.required<TeaserBlok>();
-}
-```
-
-### Grid component
-
-A grid component that renders nested components in columns:
-
-```typescript
-// src/app/components/grid/grid.component.ts
-import { Component, ChangeDetectionStrategy, input } from '@angular/core';
-import { SbBlokDirective, type SbBlokData } from '@storyblok/angular';
-
-export interface GridBlok extends SbBlokData {
-  columns?: SbBlokData[];
-}
-
-@Component({
-  selector: 'app-grid',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [SbBlokDirective],
-  template: `
-    <div class="grid">
-      @for (column of blok().columns ?? []; track column._uid) {
-        <ng-container [sbBlok]="column" />
-      }
-    </div>
-  `,
-  styles: `
-    .grid {
-      display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
-      gap: 1.5rem;
-      padding: 1rem 0;
-    }
-  `,
-})
-export class GridComponent {
-  readonly blok = input.required<GridBlok>();
-}
-```
-
-### Feature component
-
-A feature card component:
-
-```typescript
-// src/app/components/feature/feature.component.ts
-import { Component, ChangeDetectionStrategy, input } from '@angular/core';
-import { type SbBlokData } from '@storyblok/angular';
-
-export interface FeatureBlok extends SbBlokData {
-  name?: string;
-  description?: string;
-}
-
-@Component({
-  selector: 'app-feature',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  template: `
-    <div class="feature">
-      <h3>{{ blok().name }}</h3>
-      <p>{{ blok().description }}</p>
-    </div>
-  `,
-  styles: `
-    .feature {
-      padding: 1.5rem;
-      background: white;
-      border: 1px solid #e2e8f0;
-      border-radius: 8px;
-      box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
-    }
-    .feature h3 {
-      margin: 0 0 0.5rem;
-      color: #1a202c;
-    }
-    .feature p {
-      margin: 0;
-      color: #718096;
-    }
-  `,
-})
-export class FeatureComponent {
-  readonly blok = input.required<FeatureBlok>();
-}
-```
-
-### Register components
-
-Create a component registry with lazy loading:
-
-```typescript
-// src/app/storyblok.components.ts
-import { type StoryblokComponentsMap } from '@storyblok/angular';
-
-export const storyblokComponents: StoryblokComponentsMap = {
-  page: () => import('./components/page/page.component').then((m) => m.PageComponent),
-  teaser: () => import('./components/teaser/teaser.component').then((m) => m.TeaserComponent),
-  grid: () => import('./components/grid/grid.component').then((m) => m.GridComponent),
-  feature: () => import('./components/feature/feature.component').then((m) => m.FeatureComponent),
-};
-```
-
-Update `app.config.ts` to use the component registry:
-
-```typescript
-import { storyblokComponents } from './storyblok.components';
-
-// In providers array:
-provideStoryblok(
-  { accessToken: 'YOUR_ACCESS_TOKEN', region: 'eu' },
-  withStoryblokComponents(storyblokComponents),
-  withLivePreview()
-)
-```
-
-## Fetch and display content
-
-### Create a catch-all route
-
-Create a route component that fetches content based on the URL:
-
-```typescript
-// src/app/routes/catch-all/catch-all.component.ts
-import {
-  Component,
-  ChangeDetectionStrategy,
-  inject,
-  computed,
-  OnInit,
-  linkedSignal,
-  input,
-} from '@angular/core';
-import {
-  type ISbStoryData,
-  type SbBlokData,
-  SbBlokDirective,
-  LivePreviewService,
-} from '@storyblok/angular';
-
-@Component({
-  selector: 'app-catch-all',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [SbBlokDirective],
-  template: `
-    <div class="container">
-      <ng-container [sbBlok]="storyContent()" />
-      @if (!storyContent()) {
-        <div class="not-found">
-          <h2>Page not found</h2>
-          <p>The requested page could not be found.</p>
-        </div>
-      }
-    </div>
-  `,
-  styles: `
-    .container {
-      max-width: 1200px;
-      margin: 0 auto;
-      padding: 2rem;
-    }
-    .not-found {
-      text-align: center;
-      padding: 4rem 2rem;
-    }
-  `,
-})
-export class CatchAllComponent implements OnInit {
-  private readonly livePreview = inject(LivePreviewService);
-
-  // Story data from route resolver
-  readonly storyInput = input<ISbStoryData | null>(null, { alias: 'story' });
-  
-  // Writable signal that can be updated by live preview
-  readonly story = linkedSignal(() => this.storyInput());
-  
-  readonly storyContent = computed(() => this.story()?.content as SbBlokData | undefined);
-
-  ngOnInit(): void {
-    // Enable live preview updates
-    this.livePreview.listen((updatedStory) => {
-      this.story.set(updatedStory);
-    });
-  }
-}
-```
-
-### Set up routing
-
-Configure routes with a resolver to fetch content:
-
-```typescript
-// src/app/app.routes.ts
-import { inject } from '@angular/core';
-import { ActivatedRouteSnapshot, Routes } from '@angular/router';
-import { StoryblokService } from '@storyblok/angular';
-
-export const routes: Routes = [
-  {
-    path: '**',
-    loadComponent: () =>
-      import('./routes/catch-all/catch-all.component').then((m) => m.CatchAllComponent),
-    resolve: {
-      story: async (route: ActivatedRouteSnapshot) => {
-        const slug = route.url.map((s) => s.path).join('/') || 'home';
-        const client = inject(StoryblokService).getClient();
-        const { data } = await client.stories.get(slug, {
-          query: { version: 'draft' },
-        });
-        return data?.story;
-      },
-    },
-  },
-];
-```
-
-## Add rich text support
-
-### Create a page with rich text
-
-Update the page component to support rich text fields:
-
-```typescript
-// src/app/components/page/page.component.ts
-import { Component, ChangeDetectionStrategy, input } from '@angular/core';
-import {
-  SbBlokDirective,
-  SbRichTextComponent,
-  type SbBlokData,
-  type StoryblokRichTextNode,
-} from '@storyblok/angular';
-
-export interface PageBlok extends SbBlokData {
-  body?: SbBlokData[];
-  content?: StoryblokRichTextNode;
-}
-
-@Component({
-  selector: 'app-page',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [SbBlokDirective, SbRichTextComponent],
-  template: `
-    <div class="page">
-      @for (blok of blok().body ?? []; track blok._uid) {
-        <ng-container [sbBlok]="blok" />
-      }
-      
-      @if (blok().content) {
-        <div class="rich-text">
-          <sb-rich-text [doc]="blok().content!" />
-        </div>
-      }
-    </div>
-  `,
-  styles: `
-    .rich-text {
-      max-width: 65ch;
-      margin: 2rem auto;
-      line-height: 1.7;
-    }
-  `,
-})
-export class PageComponent {
-  readonly blok = input.required<PageBlok>();
-}
-```
-
-### Custom link component for rich text
-
-Create a custom link component to handle internal and external links:
-
-```typescript
-// src/app/components/richtext/link.component.ts
-import { Component, ChangeDetectionStrategy, input, computed } from '@angular/core';
-import { RouterLink } from '@angular/router';
-import { SbRichTextNodeComponent, type AngularRenderNode } from '@storyblok/angular';
-
-interface LinkProps {
-  href?: string;
-  target?: string;
-  linktype?: string;
-  children?: AngularRenderNode[];
-}
-
-@Component({
-  selector: 'app-rich-link',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [SbRichTextNodeComponent, RouterLink],
-  template: `
-    @if (isInternal()) {
-      <a [routerLink]="href()" class="link internal">
-        <sb-rich-text-node [nodes]="children()" />
-      </a>
-    } @else {
-      <a [href]="href()" [target]="target()" class="link external" rel="noopener">
-        <sb-rich-text-node [nodes]="children()" />
-      </a>
-    }
-  `,
-  styles: `
-    .link {
-      color: #667eea;
-      text-decoration: underline;
-    }
-    .link:hover {
-      color: #764ba2;
-    }
-  `,
-})
-export class RichLinkComponent {
-  readonly props = input<LinkProps>({});
-  
-  readonly href = computed(() => this.props().href ?? '');
-  readonly target = computed(() => this.props().target ?? '_self');
-  readonly linktype = computed(() => this.props().linktype);
-  readonly children = computed(() => this.props().children ?? []);
-  
-  readonly isInternal = computed(() => this.linktype() === 'story');
-}
-```
-
-Register the custom rich text component:
-
-```typescript
-// src/app/app.config.ts
-import { withStoryblokRichtextComponents } from '@storyblok/angular';
-import { RichLinkComponent } from './components/richtext/link.component';
-
-provideStoryblok(
-  { accessToken: 'YOUR_ACCESS_TOKEN', region: 'eu' },
-  withStoryblokComponents(storyblokComponents),
-  withLivePreview(),
-  withStoryblokRichtextComponents({
-    link: RichLinkComponent,
-  })
-)
-```
-
-## Handle embedded components in rich text
-
-When you embed Storyblok components inside rich text fields, create a blok component to render them:
-
-```typescript
-// src/app/components/richtext/blok.component.ts
-import { Component, ChangeDetectionStrategy, input, computed } from '@angular/core';
-import { SbBlokDirective, type SbBlokData, type AngularRenderNode } from '@storyblok/angular';
-
-interface BlokProps {
-  body?: SbBlokData[];
-  children?: AngularRenderNode[];
-}
-
-@Component({
-  selector: 'app-rich-blok',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [SbBlokDirective],
-  template: `
-    @for (blok of body(); track blok._uid) {
-      <ng-container [sbBlok]="blok" />
-    }
-  `,
-})
-export class RichBlokComponent {
-  readonly props = input<BlokProps>({});
-  readonly body = computed(() => this.props().body ?? []);
-}
-```
-
-Register it in the rich text components:
-
-```typescript
-withStoryblokRichtextComponents({
-  link: RichLinkComponent,
-  blok: RichBlokComponent,
-})
-```
-
-## Resolve relations
-
-When your content references other stories (like an article referencing an author), resolve these relations:
-
-### Configure relation resolution
-
-```typescript
-// In your route resolver
-const { data } = await client.stories.get(slug, {
-  query: {
-    version: 'draft',
-    resolve_relations: 'article.author,article.categories',
-  },
-});
-```
-
-### Enable live preview for relations
-
-```typescript
-provideStoryblok(
-  { accessToken: 'YOUR_ACCESS_TOKEN', region: 'eu' },
-  withStoryblokComponents(storyblokComponents),
-  withLivePreview({
-    resolveRelations: ['article.author', 'article.categories'],
-  })
-)
-```
-
-### Use resolved relations in components
-
-```typescript
-// src/app/components/article/article.component.ts
-import { Component, ChangeDetectionStrategy, input } from '@angular/core';
-import { type SbBlokData, type ISbStoryData } from '@storyblok/angular';
-
-export interface ArticleBlok extends SbBlokData {
-  title?: string;
-  author?: ISbStoryData; // Resolved relation
-  categories?: ISbStoryData[]; // Resolved relations
-}
-
-@Component({
-  selector: 'app-article',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-  template: `
-    <article>
-      <h1>{{ blok().title }}</h1>
-      @if (blok().author) {
-        <p class="author">By {{ blok().author.content.name }}</p>
-      }
-      @if (blok().categories?.length) {
-        <div class="categories">
-          @for (category of blok().categories; track category.uuid) {
-            <span class="tag">{{ category.content.name }}</span>
-          }
-        </div>
-      }
-    </article>
-  `,
-})
-export class ArticleComponent {
-  readonly blok = input.required<ArticleBlok>();
-}
-```
-
-## Best practices
-
-### Use lazy loading
-
-Register components with lazy loading to reduce initial bundle size:
-
-```typescript
-const storyblokComponents: StoryblokComponentsMap = {
-  // Good: Lazy loaded
-  page: () => import('./components/page').then((m) => m.PageComponent),
-  
-  // Avoid: Eagerly loaded (increases bundle size)
-  // page: PageComponent,
-};
-```
-
-### Type your blok data
-
-Create interfaces that extend `SbBlokData` for type safety:
-
-```typescript
-interface TeaserBlok extends SbBlokData {
-  headline?: string;
-  description?: string;
-  image?: {
-    filename: string;
-    alt: string;
-  };
-}
-```
-
-### Use signals for reactivity
-
-Angular's signals work well with Storyblok:
-
-```typescript
-readonly blok = input.required<TeaserBlok>();
-readonly headline = computed(() => this.blok().headline ?? 'Default');
-```
-
-### Handle missing content gracefully
-
-Always handle cases where content might not exist:
-
-```typescript
-template: `
-  @if (blok().image?.filename) {
-    <img [src]="blok().image.filename" [alt]="blok().image.alt" />
-  }
-`
-```
-
-## Next steps
-
-- Explore the [Storyblok documentation](https://www.storyblok.com/docs)
-- Learn about [image optimization](https://www.storyblok.com/docs/image-service)
-- Set up [preview and production environments](https://www.storyblok.com/docs/guide/in-depth/environments)
-- Configure [webhooks for cache invalidation](https://www.storyblok.com/docs/guide/in-depth/webhooks)
diff --git a/packages/angular/package.json b/packages/angular/package.json
index 39e8c181b..7e4474429 100644
--- a/packages/angular/package.json
+++ b/packages/angular/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@storyblok/angular",
-  "version": "1.0.1",
+  "version": "1.2.1",
   "private": false,
   "description": "Official Angular integration for the Storyblok Headless CMS",
   "author": "Storyblok",
diff --git a/packages/angular/src/lib/richtext/rich-text.component.spec.ts b/packages/angular/src/lib/richtext/rich-text.component.spec.ts
index 68743c577..d742e50f5 100644
--- a/packages/angular/src/lib/richtext/rich-text.component.spec.ts
+++ b/packages/angular/src/lib/richtext/rich-text.component.spec.ts
@@ -2,6 +2,7 @@ import { Component, input, Type } from '@angular/core';
 import { ComponentFixture, TestBed } from '@angular/core/testing';
 import { SbRichTextComponent } from './rich-text.component';
 import { StoryblokRichtextResolver } from './richtext.feature';
+import type { SbAngularRichTextRenderContext } from './richtext.feature';
 import type { SbRichTextDoc, SbRichTextNode } from '@storyblok/richtext';
 import type { SbAngularRichTextProps } from '../types';
 import {
@@ -40,6 +41,32 @@ class MockCustomMarkComponent {
   readonly data = input.required<SbAngularRichTextProps<'link'>>();
 }
 
+/**
+ * Mock custom text component — uppercases the text content.
+ */
+@Component({
+  selector: 'app-custom-text',
+  standalone: true,
+  template: `<span class="custom-text">{{ data().text.toUpperCase() }}</span>`,
+})
+class MockCustomTextComponent {
+  readonly data = input.required<SbAngularRichTextProps<'text'>>();
+}
+
+/**
+ * Recursive text component: passes the text node back into sb-rich-text.
+ * Without loop prevention this causes infinite recursion.
+ */
+@Component({
+  selector: 'app-recursive-text',
+  standalone: true,
+  imports: [SbRichTextComponent],
+  template: `<sb-rich-text [sbDocument]="data()" />`,
+})
+class RecursiveTextComponent {
+  readonly data = input.required<SbAngularRichTextProps<'text'>>();
+}
+
 /**
  * Creates a mock resolver that matches the StoryblokRichtextResolver interface.
  * By default returns null for all types (native HTML rendering).
@@ -252,6 +279,201 @@ describe('SbRichTextComponent', () => {
       expect(pre?.className).toBe('language-js');
       expect(code?.getAttribute('data-lang')).toBe('js');
     });
+
+    it('passes sbData to custom components via context input', async () => {
+      @Component({
+        selector: 'app-ctx-text',
+        standalone: true,
+        template: `<span class="ctx-text">{{ prefix() }}{{ data().text }}</span>`,
+      })
+      class ContextTextComponent {
+        readonly data    = input.required<SbAngularRichTextProps<'text'>>();
+        readonly context = input<SbAngularRichTextRenderContext>();
+        readonly prefix  = () => (this.context()?.data as { prefix?: string } | undefined)?.prefix ?? '';
+      }
+
+      TestBed.resetTestingModule();
+      await TestBed.configureTestingModule({
+        imports: [SbRichTextComponent],
+        providers: [
+          {
+            provide: StoryblokRichtextResolver,
+            useValue: createMockResolver({ text: ContextTextComponent }),
+          },
+        ],
+      }).compileComponents();
+      fixture = TestBed.createComponent(SbRichTextComponent);
+
+      const node: SbRichTextNode = {
+        type: 'paragraph',
+        content: [text('world')],
+      };
+      fixture.componentRef.setInput('sbDocument', node);
+      fixture.componentRef.setInput('sbData', { prefix: 'hello ' });
+      fixture.detectChanges();
+
+      const span = fixture.nativeElement.querySelector('.ctx-text');
+      expect(span?.textContent).toBe('hello world');
+    });
+
+    it('does not throw when a custom component does not declare a context input', async () => {
+      // MockCustomParagraphComponent has no context input — setInput should be caught silently.
+      const node: SbRichTextNode = { type: 'paragraph', content: [text('Hello')] };
+      TestBed.resetTestingModule();
+      await TestBed.configureTestingModule({
+        imports: [SbRichTextComponent],
+        providers: [
+          {
+            provide: StoryblokRichtextResolver,
+            useValue: createMockResolver({ paragraph: MockCustomParagraphComponent }),
+          },
+        ],
+      }).compileComponents();
+      fixture = TestBed.createComponent(SbRichTextComponent);
+
+      fixture.componentRef.setInput('sbDocument', node);
+      fixture.componentRef.setInput('sbData', { foo: 'bar' });
+
+      expect(() => fixture.detectChanges()).not.toThrow();
+      expect(fixture.nativeElement.querySelector('.custom-node')).toBeTruthy();
+    });
+
+    it('passes sbData to custom mark components via context input', async () => {
+      @Component({
+        selector: 'app-ctx-bold',
+        standalone: true,
+        template: `<b class="ctx-bold" [attr.data-prefix]="prefix()"><ng-content /></b>`,
+      })
+      class ContextBoldComponent {
+        readonly data    = input.required<SbAngularRichTextProps<'bold'>>();
+        readonly context = input<SbAngularRichTextRenderContext>();
+        readonly prefix  = () => (this.context()?.data as { prefix?: string } | undefined)?.prefix ?? '';
+      }
+
+      TestBed.resetTestingModule();
+      await TestBed.configureTestingModule({
+        imports: [SbRichTextComponent],
+        providers: [
+          {
+            provide: StoryblokRichtextResolver,
+            useValue: createMockResolver({ bold: ContextBoldComponent }),
+          },
+        ],
+      }).compileComponents();
+      fixture = TestBed.createComponent(SbRichTextComponent);
+
+      const node: SbRichTextNode = {
+        type: 'paragraph',
+        content: [text('hello', [{ type: 'bold' }])],
+      };
+      fixture.componentRef.setInput('sbDocument', node);
+      fixture.componentRef.setInput('sbData', { prefix: 'test' });
+      fixture.detectChanges();
+
+      const bold = fixture.nativeElement.querySelector('.ctx-bold');
+      expect(bold).toBeTruthy();
+      expect(bold.getAttribute('data-prefix')).toBe('test');
+    });
+
+    it('renders custom text component when text type is registered', async () => {
+      TestBed.resetTestingModule();
+      await TestBed.configureTestingModule({
+        imports: [SbRichTextComponent],
+        providers: [
+          {
+            provide: StoryblokRichtextResolver,
+            useValue: createMockResolver({ text: MockCustomTextComponent }),
+          },
+        ],
+      }).compileComponents();
+      fixture = TestBed.createComponent(SbRichTextComponent);
+
+      const node: SbRichTextNode = {
+        type: 'paragraph',
+        content: [text('hello'), text('world')],
+      };
+      fixture.componentRef.setInput('sbDocument', node);
+      fixture.detectChanges();
+
+      const spans = fixture.nativeElement.querySelectorAll('.custom-text');
+      expect(spans.length).toBe(2);
+      expect(spans[0].textContent.trim()).toBe('HELLO');
+      expect(spans[1].textContent.trim()).toBe('WORLD');
+    });
+
+    it('prevents infinite loop when a custom text component uses sb-rich-text internally', async () => {
+      // RecursiveTextComponent feeds the same text node back into <sb-rich-text>.
+      // Without prevention this blows the call stack.
+      // With prevention: a child EnvironmentInjector is created with 'text' excluded,
+      // so the nested <sb-rich-text> falls back to native text rendering.
+      TestBed.resetTestingModule();
+      await TestBed.configureTestingModule({
+        imports: [SbRichTextComponent],
+        providers: [
+          {
+            provide: StoryblokRichtextResolver,
+            useValue: createMockResolver({ text: RecursiveTextComponent }),
+          },
+        ],
+      }).compileComponents();
+      fixture = TestBed.createComponent(SbRichTextComponent);
+
+      const node: SbRichTextNode = {
+        type: 'paragraph',
+        content: [text('hello')],
+      };
+      fixture.componentRef.setInput('sbDocument', node);
+
+      expect(() => fixture.detectChanges()).not.toThrow();
+      expect(fixture.nativeElement.textContent).toContain('hello');
+    });
+
+    it('preserves all ancestor excluded types across multiple nesting levels', async () => {
+      // Scenario: both `paragraph` and `text` have custom components that each
+      // re-render their node via <sb-rich-text>.
+      //
+      // Without the fix the child injector for `text` creates Set(['text']),
+      // forgetting that `paragraph` is already excluded. The innermost
+      // <sb-rich-text> then re-enables the paragraph custom component and
+      // recurses infinitely.
+      //
+      // With the fix the excluded set accumulates: Set(['paragraph', 'text']),
+      // so both types fall back to native rendering at the deepest level.
+
+      @Component({
+        selector: 'app-recursive-paragraph',
+        standalone: true,
+        imports: [SbRichTextComponent],
+        template: `<sb-rich-text [sbDocument]="data()" />`,
+      })
+      class RecursiveParagraphComponent {
+        readonly data = input.required<SbAngularRichTextProps<'paragraph'>>();
+      }
+
+      TestBed.resetTestingModule();
+      await TestBed.configureTestingModule({
+        imports: [SbRichTextComponent],
+        providers: [
+          {
+            provide: StoryblokRichtextResolver,
+            useValue: createMockResolver({
+              paragraph: RecursiveParagraphComponent,
+              text: RecursiveTextComponent,
+            }),
+          },
+        ],
+      }).compileComponents();
+      fixture = TestBed.createComponent(SbRichTextComponent);
+
+      const node: SbRichTextNode = {
+        type: 'paragraph',
+        content: [text('hello')],
+      };
+      fixture.componentRef.setInput('sbDocument', node);
+
+      expect(() => fixture.detectChanges()).not.toThrow();
+      expect(fixture.nativeElement.textContent).toContain('hello');
+    });
   });
 
   // ============================================================================
diff --git a/packages/angular/src/lib/richtext/rich-text.component.ts b/packages/angular/src/lib/richtext/rich-text.component.ts
index 694dc0cf0..541575003 100644
--- a/packages/angular/src/lib/richtext/rich-text.component.ts
+++ b/packages/angular/src/lib/richtext/rich-text.component.ts
@@ -12,6 +12,7 @@ import {
   ApplicationRef,
   EnvironmentInjector,
   untracked,
+  createEnvironmentInjector,
 } from '@angular/core';
 import {
   buildStoryblokImage,
@@ -33,7 +34,11 @@ import type {
   SbRichTextImageOptions,
 } from '@storyblok/richtext';
 import { StoryblokComponent } from '../blok/sb-component.component';
-import { StoryblokRichtextResolver } from './richtext.feature';
+import {
+  StoryblokRichtextResolver,
+  STORYBLOK_RICHTEXT_EXCLUDED_TYPES,
+  type SbAngularRichTextRenderContext,
+} from './richtext.feature';
 
 @Component({
   selector: 'sb-rich-text',
@@ -62,11 +67,24 @@ export class SbRichTextComponent implements OnDestroy {
    */
   sbOptimizeImage = input<boolean | Partial<SbRichTextImageOptions>>(false);
 
+  /**
+   * Arbitrary data forwarded to every custom node/mark component via their `context` input.
+   * Use this to pass application state (e.g. locale, theme, user data) into richtext renderers
+   * without prop-drilling through the document tree.
+   *
+   * @example
+   * ```html
+   * <sb-rich-text [sbDocument]="doc" [sbData]="{ prefix: '[draft]' }" />
+   * ```
+   */
+  sbData = input<unknown>();
+
   private readonly renderer = inject(Renderer2);
   private readonly hostElement: HTMLElement = inject(ElementRef).nativeElement;
   private readonly appRef = inject(ApplicationRef);
   private readonly envInjector = inject(EnvironmentInjector);
   private readonly resolver = inject(StoryblokRichtextResolver);
+  private readonly excludedTypes = inject(STORYBLOK_RICHTEXT_EXCLUDED_TYPES);
 
   /** Prevent async work after destroy */
   private destroyed = false;
@@ -80,12 +98,16 @@ export class SbRichTextComponent implements OnDestroy {
   /** Track dynamically created components */
   private readonly componentRefs: any[] = [];
 
+  /** Track child EnvironmentInjectors created for loop prevention */
+  private readonly childInjectors: EnvironmentInjector[] = [];
+
   constructor() {
     // Use effect to reactively render when doc or optimizeImage changes
     // The effect runs synchronously during change detection, making it SSR-compatible
     effect(() => {
       const sbDocument = this.sbDocument();
       const _optimizeImage = this.sbOptimizeImage(); // Track for reactivity
+      const _data = this.sbData(); // Track for reactivity
       // Use untracked to avoid re-triggering the effect when calling render
       untracked(() => this.render(sbDocument));
     });
@@ -100,6 +122,12 @@ export class SbRichTextComponent implements OnDestroy {
       ref.destroy();
     }
     this.componentRefs.length = 0;
+
+    // destroy child injectors created for loop prevention
+    for (const injector of this.childInjectors) {
+      injector.destroy();
+    }
+    this.childInjectors.length = 0;
   }
 
   // --------------------------------------------------
@@ -182,6 +210,7 @@ export class SbRichTextComponent implements OnDestroy {
           });
 
           ref.setInput('data', mark);
+          try { ref.setInput('context', this.getContext()); } catch { /* context input not declared */ }
           this.appRef.attachView(ref.hostView);
           this.componentRefs.push(ref);
 
@@ -211,22 +240,44 @@ export class SbRichTextComponent implements OnDestroy {
     if (this.shouldAbort(version)) return;
 
     if (node.type === 'text') {
+      // Check for a custom text component before falling back to native rendering.
+      // Skip if this type is excluded (loop prevention).
+      if (!this.excludedTypes.has('text')) {
+        const syncTextComponent = this.resolver.getSync('text');
+        if (syncTextComponent) {
+          const anchor = this.renderer.createComment('sb-node');
+          this.renderer.appendChild(parent, anchor);
+          this.mountComponent(syncTextComponent, { data: node }, parent, anchor, 'text');
+          return;
+        }
+
+        if (this.resolver.has('text')) {
+          const anchor = this.renderer.createComment('sb-node');
+          this.renderer.appendChild(parent, anchor);
+          this.resolveAndMount(node, parent, anchor, version);
+          return;
+        }
+      }
+
       this.renderTextNode(node, parent, version);
       return;
     }
 
-    // Try to get cached or eagerly loaded component synchronously first
-    const syncComponent = this.resolver.getSync(node.type);
+    // Try to get cached or eagerly loaded component synchronously first.
+    // Skip if this type is excluded (loop prevention).
+    const syncComponent = !this.excludedTypes.has(node.type)
+      ? this.resolver.getSync(node.type)
+      : null;
 
     if (syncComponent) {
       const anchor = this.renderer.createComment('sb-node');
       this.renderer.appendChild(parent, anchor);
-      this.mountComponent(syncComponent, { data: node }, parent, anchor);
+      this.mountComponent(syncComponent, { data: node }, parent, anchor, node.type);
       return;
     }
 
-    // Check if this type has an async loader registered
-    if (this.resolver.has(node.type)) {
+    // Check if this type has an async loader registered (and is not excluded)
+    if (!this.excludedTypes.has(node.type) && this.resolver.has(node.type)) {
       const anchor = this.renderer.createComment('sb-node');
       this.renderer.appendChild(parent, anchor);
       this.resolveAndMount(node, parent, anchor, version);
@@ -354,7 +405,7 @@ export class SbRichTextComponent implements OnDestroy {
     if (!this.isValidAnchor(anchor, parentNode)) return;
 
     if (CustomNode) {
-      this.mountComponent(CustomNode, { data: node }, parentNode, anchor);
+      this.mountComponent(CustomNode, { data: node }, parentNode, anchor, node.type);
     } else {
       this.renderer.removeChild(parentNode, anchor);
     }
@@ -396,6 +447,7 @@ export class SbRichTextComponent implements OnDestroy {
         });
 
         ref.setInput('data', mark);
+        try { ref.setInput('context', this.getContext()); } catch { /* context input not declared */ }
         this.appRef.attachView(ref.hostView);
 
         this.componentRefs.push(ref);
@@ -437,6 +489,7 @@ export class SbRichTextComponent implements OnDestroy {
         });
 
         ref.setInput('data', mark);
+        try { ref.setInput('context', this.getContext()); } catch { /* context input not declared */ }
         this.appRef.attachView(ref.hostView);
 
         this.componentRefs.push(ref);
@@ -489,21 +542,51 @@ export class SbRichTextComponent implements OnDestroy {
     return resolved;
   }
 
+  /** Build the render context forwarded to every custom component's `context` input. */
+  private getContext(): SbAngularRichTextRenderContext {
+    const optimizeImage = this.sbOptimizeImage();
+    const ctx: SbAngularRichTextRenderContext = { data: this.sbData() };
+    if (optimizeImage) ctx.optimizeImage = optimizeImage;
+    return ctx;
+  }
+
   /** Mount dynamic component safely */
   private mountComponent(
     Component: any,
     inputs: Record<string, unknown>,
     parent: HTMLElement,
     anchor: Node,
+    excludeType?: string,
   ) {
     if (this.destroyed) return;
 
+    // When a custom component is mounted for a given type, create a child
+    // EnvironmentInjector that marks that type as excluded.  Any <sb-rich-text>
+    // rendered inside the custom component's template will inherit this injector
+    // and fall back to native HTML for that type, preventing infinite loops.
+    let injector = this.envInjector;
+    if (excludeType) {
+      injector = createEnvironmentInjector(
+        [{ provide: STORYBLOK_RICHTEXT_EXCLUDED_TYPES, useValue: new Set([...this.excludedTypes, excludeType]) }],
+        this.envInjector,
+      );
+      this.childInjectors.push(injector);
+    }
+
     const ref = createComponent(Component, {
-      environmentInjector: this.envInjector,
+      environmentInjector: injector,
     });
 
     Object.entries(inputs).forEach(([k, v]) => ref.setInput(k, v));
 
+    // Forward render context (sbData, optimizeImage) if the component declares a context input.
+    // setInput throws for undeclared inputs, so we catch and ignore it silently.
+    try {
+      ref.setInput('context', this.getContext());
+    } catch {
+      // Component does not declare a context input — skip.
+    }
+
     this.appRef.attachView(ref.hostView);
     this.componentRefs.push(ref);
 
diff --git a/packages/angular/src/lib/richtext/richtext.feature.ts b/packages/angular/src/lib/richtext/richtext.feature.ts
index cf8bf6c42..4e27dfc12 100644
--- a/packages/angular/src/lib/richtext/richtext.feature.ts
+++ b/packages/angular/src/lib/richtext/richtext.feature.ts
@@ -1,5 +1,5 @@
 import { InjectionToken, Type, Injectable, inject, InputSignal } from '@angular/core';
-import type { SbRichTextElement, SbRichTextElementByType } from '@storyblok/richtext';
+import type { SbRichTextElement, SbRichTextElementByType, SbRichTextImageOptions } from '@storyblok/richtext';
 
 import { type StoryblokFeature, BaseComponentResolver } from '../components.feature';
 
@@ -14,11 +14,39 @@ import { type StoryblokFeature, BaseComponentResolver } from '../components.feat
  */
 export type SbAngularRichTextProps<T extends SbRichTextElement> = SbRichTextElementByType[T];
 
+/**
+ * Context passed to every custom richtext node/mark component alongside its `data` input.
+ * Carries renderer-wide settings so custom components can read them without prop drilling.
+ *
+ * @example
+ * ```typescript
+ * \@Component({ template: `{{ context()?.data?.prefix }} {{ data().text }}` })
+ * class CustomTextComponent {
+ *   readonly data    = input.required<SbAngularRichTextProps<'text'>>();
+ *   readonly context = input<SbAngularRichTextRenderContext>();
+ * }
+ * ```
+ *
+ * When recursively rendering children, forward context so nested components
+ * also receive it:
+ * ```html
+ * <sb-rich-text [sbDocument]="data().content" [sbData]="context()?.data" />
+ * ```
+ */
+export interface SbAngularRichTextRenderContext {
+  /** Arbitrary user data passed as `[sbData]` on `<sb-rich-text>`. */
+  data?: unknown;
+  /** Mirror of the `[sbOptimizeImage]` input on the host `<sb-rich-text>`. */
+  optimizeImage?: boolean | Partial<SbRichTextImageOptions>;
+}
+
 /**
  * Angular component type for custom richtext nodes/marks.
+ * Declare a `context` input to receive renderer-wide context (sbData, optimizeImage).
  */
 export type SbAngularRichTextComponent<T extends SbRichTextElement> = Type<{
   data: InputSignal<SbAngularRichTextProps<T>>;
+  context?: InputSignal<SbAngularRichTextRenderContext | undefined>;
 }>;
 
 /**
@@ -65,6 +93,18 @@ export const STORYBLOK_RICHTEXT_COMPONENTS = new InjectionToken<SbAngularRichTex
   { factory: () => ({}) },
 );
 
+/**
+ * Injection token for richtext element types that should be skipped when looking up
+ * custom components. Used internally to prevent infinite loops when a custom component
+ * renders `<sb-rich-text>` for its own children — the renderer creates a child
+ * EnvironmentInjector that provides this token with the current element type, so the
+ * nested `<sb-rich-text>` falls back to native HTML rendering for that type.
+ */
+export const STORYBLOK_RICHTEXT_EXCLUDED_TYPES = new InjectionToken<ReadonlySet<string>>(
+  'STORYBLOK_RICHTEXT_EXCLUDED_TYPES',
+  { factory: () => new Set<string>() },
+);
+
 /**
  * Service for resolving richtext components with lazy loading support.
  * Caches resolved components to avoid repeated dynamic imports.
diff --git a/packages/angular/src/public-api.ts b/packages/angular/src/public-api.ts
index 697886344..2b5913fc9 100644
--- a/packages/angular/src/public-api.ts
+++ b/packages/angular/src/public-api.ts
@@ -27,6 +27,7 @@ export type {
   SbAngularRichTextComponentMap,
   SbAngularRichTextComponent,
   SbAngularRichTextProps,
+  SbAngularRichTextRenderContext,
 } from './lib/richtext/richtext.feature';
 
 export type { Story } from '@storyblok/api-client';
diff --git a/packages/astro/cypress/e2e/index.cy.js b/packages/astro/cypress/e2e/index.cy.js
index fb523ca56..5ce13df87 100644
--- a/packages/astro/cypress/e2e/index.cy.js
+++ b/packages/astro/cypress/e2e/index.cy.js
@@ -3,6 +3,7 @@ Tests:
 - Bridge should be loaded
 - storyblokEditable attributes are assigned
 - globally loaded component is rendered correctly
+- TDZ fix works for manually registered components
 */
 
 describe("@storyblok/astro", () => {
@@ -31,6 +32,26 @@ describe("@storyblok/astro", () => {
     cy.visit("http://localhost:4321/");
     cy.get("[data-test=custom-fallback-component]").should("exist");
   });
+
+  /**
+   * TDZ (Temporal Dead Zone) Test
+   *
+   * Verifies that manually-registered components don't cause
+   * "Cannot access 'X' before initialization" errors when:
+   * 1. A component is registered in astro.config.mjs
+   * 2. The same component is directly imported in a page
+   *
+   * If the page loads and renders correctly, the TDZ fix is working.
+   */
+  it("TDZ fix: directly imported components work alongside registration", () => {
+    cy.visit("http://localhost:4321/tdz-test");
+    // Page should load without TDZ errors
+    cy.contains("TDZ Test Page").should("exist");
+    cy.contains("If you can see this, the TDZ fix is working correctly.").should("exist");
+    // Directly imported Teaser component should render
+    cy.contains("Direct Import Test").should("exist");
+  });
+
   /* it("RichText Renderer renders embedded bloks correctly", () => {
     cy.visit("http://localhost:4321/");
     cy.get("[data-test=embedded-blok]").should("exist");
diff --git a/packages/astro/package.json b/packages/astro/package.json
index 0dcc4fbff..15b9653bc 100644
--- a/packages/astro/package.json
+++ b/packages/astro/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/astro",
   "type": "module",
-  "version": "10.0.1",
+  "version": "10.2.0",
   "private": false,
   "description": "Official Astro integration for the Storyblok Headless CMS",
   "author": "Storyblok",
diff --git a/packages/astro/playground/test/src/pages/tdz-test.astro b/packages/astro/playground/test/src/pages/tdz-test.astro
new file mode 100644
index 000000000..e832f9d94
--- /dev/null
+++ b/packages/astro/playground/test/src/pages/tdz-test.astro
@@ -0,0 +1,31 @@
+---
+/**
+ * TDZ (Temporal Dead Zone) Test Page
+ *
+ * This page verifies that manually-registered components don't cause
+ * "Cannot access 'X' before initialization" errors during SSR builds.
+ *
+ * The TDZ issue occurs when:
+ * 1. A component is registered in astro.config.mjs: components: { teaser: '...' }
+ * 2. The same component is directly imported in a page (like below)
+ * 3. During bundling, the registration code may execute before the component is defined
+ *
+ * If this page builds successfully, the TDZ fix is working.
+ */
+import Teaser from '@shared/storyblok/Teaser.astro';
+import Grid from '@shared/storyblok/Grid.astro';
+---
+
+<html>
+  <head>
+    <title>TDZ Test</title>
+  </head>
+  <body>
+    <h1>TDZ Test Page</h1>
+    <p>If you can see this, the TDZ fix is working correctly.</p>
+
+    <!-- Direct usage of manually-registered components -->
+    <Teaser blok={{ component: 'teaser', headline: 'Direct Import Test', _uid: '1' }} />
+    <Grid blok={{ component: 'grid', columns: [], _uid: '2' }} />
+  </body>
+</html>
diff --git a/packages/astro/src/components/StoryblokRichText.astro b/packages/astro/src/components/StoryblokRichText.astro
index 884810916..3de29fde1 100644
--- a/packages/astro/src/components/StoryblokRichText.astro
+++ b/packages/astro/src/components/StoryblokRichText.astro
@@ -6,9 +6,8 @@ interface Props extends SbAstroRichTextRenderContext {
   document: SbRichTextInput;
 }
 
-const { document, components, optimizeImage } = Astro.props;
-
+const { document, components, optimizeImage, data } = Astro.props;
 const nodes = normalizeNodes(document);
 ---
 
-<RenderChildren nodes={nodes} options={{ components, optimizeImage }} />
+<RenderChildren nodes={nodes} options={{ components, optimizeImage, data }} />
diff --git a/packages/astro/src/components/richtext/RenderLinkGroup.astro b/packages/astro/src/components/richtext/RenderLinkGroup.astro
index 1bdf569dc..4a78cb417 100644
--- a/packages/astro/src/components/richtext/RenderLinkGroup.astro
+++ b/packages/astro/src/components/richtext/RenderLinkGroup.astro
@@ -20,7 +20,7 @@ const Custom = components ? components[linkMark.type] : undefined;
 
 {
   isValidAstroComponent(Custom) ? (
-    <Custom {...linkMark}>
+    <Custom {...linkMark} context={options}>
       <RenderLinkInner nodes={nodes} options={options} />
     </Custom>
   ) : (
diff --git a/packages/astro/src/components/richtext/RenderNode.astro b/packages/astro/src/components/richtext/RenderNode.astro
index 005af24e5..8105f1d1a 100644
--- a/packages/astro/src/components/richtext/RenderNode.astro
+++ b/packages/astro/src/components/richtext/RenderNode.astro
@@ -19,16 +19,22 @@ interface Props {
 }
 const { node, options } = Astro.props;
 const components = options.components;
-const Custom = components && node.type !== 'text' ? components[node.type] : undefined;
+const Custom = components ? components[node.type] : undefined;
+
+// When passing context to a custom component, exclude that component type
+// to prevent infinite loops if the custom component uses StoryblokRichText internally
+const contextForCustom = Custom
+  ? { ...options, components: { ...components, [node.type]: undefined } }
+  : options;
 ---
 
 {
-  node.type === 'text' ? (
-    <RenderTextNodeWithMarks node={node} marks={node.marks} options={options} />
-  ) : isValidAstroComponent(Custom) ? (
-    <Custom {...node} context={options}>
-      {node.content && <RenderChildren nodes={node.content} options={options} />}
+  isValidAstroComponent(Custom) ? (
+    <Custom {...node} context={contextForCustom}>
+      {node.type !== 'text' && node.content && <RenderChildren nodes={node.content} options={options} />}
     </Custom>
+  ) : node.type === 'text' ? (
+    <RenderTextNodeWithMarks node={node} marks={node.marks} options={options} />
   ) : node.type === 'image' ? (
     <RenderImage node={node} options={options} />
   ) : node.type === 'blok' ? (
diff --git a/packages/astro/src/components/richtext/RenderTextNodeWithMarks.astro b/packages/astro/src/components/richtext/RenderTextNodeWithMarks.astro
index 77ed58ea0..1f7308b51 100644
--- a/packages/astro/src/components/richtext/RenderTextNodeWithMarks.astro
+++ b/packages/astro/src/components/richtext/RenderTextNodeWithMarks.astro
@@ -23,7 +23,7 @@ const MarkComponent = mark && components ? components[mark.type] : undefined;
   reversedMarks.length === 0 ? (
     node.text
   ) : isValidAstroComponent(MarkComponent) ? (
-    <MarkComponent {...mark}>
+    <MarkComponent {...mark} context={options}>
       <Astro.self node={node} marks={rest} options={options} />
     </MarkComponent>
   ) : (
diff --git a/packages/astro/src/utils/richtext-helpers.ts b/packages/astro/src/utils/richtext-helpers.ts
index 8217ec586..15843ee80 100644
--- a/packages/astro/src/utils/richtext-helpers.ts
+++ b/packages/astro/src/utils/richtext-helpers.ts
@@ -8,6 +8,7 @@ export type SbAstroRichTextComponentMap = {
 export interface SbAstroRichTextRenderContext {
   optimizeImage?: boolean | SbRichTextImageOptions;
   components?: SbAstroRichTextComponentMap;
+  data?: unknown;
 }
 export type SbAstroRichTextProps<
   T extends SbRichTextElement,
diff --git a/packages/astro/src/vite-plugins/vite-plugin-import-storyblok-components.ts b/packages/astro/src/vite-plugins/vite-plugin-import-storyblok-components.ts
index 270b31b7f..eed28f38c 100644
--- a/packages/astro/src/vite-plugins/vite-plugin-import-storyblok-components.ts
+++ b/packages/astro/src/vite-plugins/vite-plugin-import-storyblok-components.ts
@@ -3,14 +3,12 @@ import { normalizePath } from '../utils/normalizePath';
 import { toCamelCase } from '../utils/toCamelCase';
 import type { Plugin } from 'vite';
 
-// Virtual module identifiers for Vite's module system
 const VIRTUAL_MODULE_ID = 'virtual:import-storyblok-components';
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
+
 /**
- * Vite plugin that automatically imports Storyblok components from a specified directory
- * and merges them with optional user-provided component mappings.
- *
- * @returns Vite plugin object
+ * Vite plugin that auto-imports Storyblok components from a directory
+ * and merges them with user-provided component mappings.
  */
 export function vitePluginImportStoryblokComponents(
   components: Record<string, string>,
@@ -20,81 +18,75 @@ export function vitePluginImportStoryblokComponents(
 ): Plugin {
   return {
     name: 'vite-plugin-import-storyblok-components',
-    /**
-     * Resolves virtual module imports
-     */
+
     async resolveId(id: string) {
       if (id === VIRTUAL_MODULE_ID) {
         return RESOLVED_VIRTUAL_MODULE_ID;
       }
     },
 
-    /**
-     * Generates the virtual module content with dynamic imports
-     */
     async load(id: string) {
       if (id !== RESOLVED_VIRTUAL_MODULE_ID) {
         return;
       }
 
-      // Resolve fallback component import
-      const fallbackImport = await resolveFallbackComponent(
+      const fallbackRegistration = await resolveFallbackComponent(
         this,
         componentsDir,
         enableFallbackComponent,
         customFallbackComponent,
       );
 
-      const manualImports = await resolveUserComponents(
+      const manualRegistrations = await resolveUserComponents(
         this,
         components,
         componentsDir,
         enableFallbackComponent,
       );
 
-      // Generate the virtual module code
-      const moduleCode = generateModuleCode(
-        componentsDir,
-        fallbackImport,
-        manualImports,
-      );
-
       return {
-        code: moduleCode,
+        code: generateModuleCode(componentsDir, fallbackRegistration, manualRegistrations),
         moduleType: 'js',
       };
     },
   };
 }
+
+export interface ComponentRegistrationParts {
+  importStatement: string;
+  wrapperDefinition: string;
+  registrationCall: string;
+}
+
 /**
- * Generates the complete virtual module code including:
- * - Auto-imported components via glob
- * - User-provided component imports
- * - Optional fallback component
- *
- * @param componentsDir - Base directory of components
- * @param fallbackImport - Import statement for fallback (if any)
- * @param manualImports - Explicit imports generated from user-provided components
- * @returns Virtual module source code
+ * Generates the virtual module code with:
+ * - Static imports at the top for proper hoisting
+ * - Glob-imported components from storyblok folder
+ * - Manual and fallback component registrations
  */
-function generateModuleCode(
+export function generateModuleCode(
   componentsDir: string,
-  fallbackImport: string,
-  manualImports: string[],
+  fallbackRegistration: ComponentRegistrationParts | null,
+  manualRegistrations: ComponentRegistrationParts[],
 ): string {
-  // Normalize components directory path for Vite globbing
   const normalizedComponentsDir = normalizePath(componentsDir);
-
-  // Only look into the storyblok folder
   const globPattern = `${normalizedComponentsDir}/storyblok/**/*.astro`;
 
+  const allRegistrations = [...manualRegistrations];
+  if (fallbackRegistration) {
+    allRegistrations.push(fallbackRegistration);
+  }
+
+  const importStatements = allRegistrations.map(r => r.importStatement);
+  const wrapperDefinitions = allRegistrations.map(r => r.wrapperDefinition);
+  const registrationCalls = allRegistrations.map(r => r.registrationCall);
+
   return `
-    // Import utilities and fallback component
     import { toCamelCase } from '@storyblok/astro';
+    ${importStatements.join('\n    ')}
 
-    // Dynamically import all Storyblok components using Vite's glob import
     const modules = import.meta.glob('${globPattern}', { eager: true });
-    // Process imported modules into a components object
+
     const storyblokComponents = {};
     const createComponentLoader = (module) => {
       return async () => module?.default ?? module;
@@ -106,20 +98,19 @@ function generateModuleCode(
         get: () => createComponentLoader(component),
       });
     };
+
     for (const filePath in modules) {
-      // Extract component name from file path (remove extension)
       const fileName = filePath.split('/').pop();
-      const componentName = toCamelCase(fileName?.replace(/\.[^/.]+$/, '') ?? '');
+      const componentName = toCamelCase(fileName?.replace(/\\.[^/.]+$/, '') ?? '');
       if (componentName) {
         registerComponent(componentName, modules[filePath]);
       }
     }
-    
-    // Manual components
-    ${manualImports.join('\n\n')}
-    // Add fallback component if enabled
-    ${fallbackImport}    
-    // Export the components object for use in Storyblok initialization
+
+    ${wrapperDefinitions.join('\n    ')}
+
+    ${registrationCalls.join('\n    ')}
+
     export { storyblokComponents };
   `.trim();
 }
@@ -129,21 +120,18 @@ async function resolveFallbackComponent(
   componentsDir: string,
   enableFallbackComponent: boolean,
   customFallbackComponent?: string,
-): Promise<string> {
+): Promise<ComponentRegistrationParts | null> {
   if (!enableFallbackComponent) {
-    return '';
+    return null;
   }
   if (!customFallbackComponent) {
-    return createComponentRegistrationCode({
+    return createComponentRegistrationParts({
       componentName: 'FallbackComponent',
       importPath: '@storyblok/astro/FallbackComponent.astro',
     });
   }
 
-  const componentPath = getComponentFullPath(
-    componentsDir,
-    customFallbackComponent,
-  );
+  const componentPath = getComponentFullPath(componentsDir, customFallbackComponent);
   const resolved = await ctx.resolve(componentPath);
   if (!resolved) {
     throw new Error(
@@ -151,27 +139,19 @@ async function resolveFallbackComponent(
     );
   }
 
-  return createComponentRegistrationCode({
+  return createComponentRegistrationParts({
     componentName: 'FallbackComponent',
     importPath: resolved.id,
   });
 }
-/**
- * Resolves user-provided Storyblok components into import statements.
- *
- * @param ctx - Vite plugin context (`this` in load hook)
- * @param components - User-specified mapping of blok names to component paths
- * @param componentsDir - Base directory for components
- * @param enableFallback - Whether to silently skip unresolved components
- * @returns Object containing import statements
- */
+
 async function resolveUserComponents(
   ctx: any,
   components: Record<string, string>,
   componentsDir: string,
   enableFallback: boolean,
-): Promise<string[]> {
-  const resolvedComponents: string[] = [];
+): Promise<ComponentRegistrationParts[]> {
+  const resolvedComponents: ComponentRegistrationParts[] = [];
 
   for (const [blokName, componentPath] of Object.entries(components)) {
     const fullPath = getComponentFullPath(componentsDir, componentPath);
@@ -186,7 +166,7 @@ async function resolveUserComponents(
       continue;
     };
     const componentName = toCamelCase(blokName);
-    resolvedComponents.push(createComponentRegistrationCode({
+    resolvedComponents.push(createComponentRegistrationParts({
       componentName,
       importPath: resolved.id,
     }));
@@ -194,22 +174,6 @@ async function resolveUserComponents(
   return resolvedComponents;
 }
 
-/**
- * Builds the full normalized path to an Astro component file.
- *
- * - Ensures both the components directory and the component path
- *   are normalized (leading slash, no trailing slash, no duplicates).
- * - Concatenates them into a single path.
- * - Ensures the `.astro` extension is present.
- *
- * @param componentsDir - Base directory where Astro components live
- * @param componentPath - Relative path (or subpath) to the component
- * @returns Full normalized path ending with `.astro`
- *
- * @example
- * getComponentFullPath("components", "ui/Button");
- * // "/components/ui/Button.astro"
- */
 function getComponentFullPath(
   componentsDir: string,
   componentPath: string,
@@ -219,17 +183,29 @@ function getComponentFullPath(
   return normalizeAstroExtension(fullComponentPath);
 }
 
-interface CreateComponentRegistrationCodeOptions {
+interface CreateComponentRegistrationPartsOptions {
   componentName: string;
   importPath: string;
 }
 
-function createComponentRegistrationCode({
+/**
+ * Generates structured registration parts for a component.
+ *
+ * Uses a getter wrapper to avoid TDZ (Temporal Dead Zone) errors.
+ * When Vite bundles modules, direct references to imported components
+ * can cause "Cannot access 'X' before initialization" errors.
+ * The getter defers access until the component is actually needed.
+ */
+export function createComponentRegistrationParts({
   componentName,
   importPath,
-}: CreateComponentRegistrationCodeOptions): string {
-  return `
-  import ${componentName} from '${importPath}';
-  registerComponent('${componentName}', ${componentName});
-`.trim();
+}: CreateComponentRegistrationPartsOptions): ComponentRegistrationParts {
+  const varName = `__${componentName}_component__`;
+  const wrapperName = `__${componentName}_wrapper__`;
+
+  return {
+    importStatement: `import ${varName} from '${importPath}';`,
+    wrapperDefinition: `const ${wrapperName} = { get default() { return ${varName}; } };`,
+    registrationCall: `registerComponent('${componentName}', ${wrapperName});`,
+  };
 }
diff --git a/packages/astro/tests/richtext.test.ts b/packages/astro/tests/richtext.test.ts
index 792b8aa7d..33227d71e 100644
--- a/packages/astro/tests/richtext.test.ts
+++ b/packages/astro/tests/richtext.test.ts
@@ -3,10 +3,12 @@ import { customRendererFixture, integrationFixtures, linkFixtures, markFixtures,
 import { experimental_AstroContainer as AstroContainer } from 'astro/container';
 import StoryblokRichText from '../src/components/StoryblokRichText.astro';
 import Heading from './richtext/Heading.astro';
+import HeadingWithRichText from './richtext/HeadingWithRichText.astro';
 import Bold from './richtext/Bold.astro';
 import CustomLink from './richtext/CustomLink.astro';
 import CodeBlock from './richtext/CodeBlock.astro';
 import CustomTable from './richtext/CustomTable.astro';
+import CustomText from './richtext/CustomText.astro';
 // Removes source file and location attributes that Astro adds for hydration
 const clean = (result: string) => result.replace(/ data-astro-source-file="[^"]*"/g, '').replace(/ data-astro-source-loc="[^"]*"/g, '');
 
@@ -168,5 +170,32 @@ describe('storyblok Richtext', async () => {
       });
       expect(clean(result)).toBe(table.expected);
     });
+    const text_node = customRendererFixture.text_node;
+    it(text_node.title, async () => {
+      const container = await AstroContainer.create();
+      const result = await container.renderToString(StoryblokRichText, {
+        props: {
+          document: text_node.input,
+          data: { prefix: '[prefix]' },
+          components: {
+            text: CustomText,
+          },
+        },
+      });
+      expect(clean(result)).toBe(text_node.expected);
+    });
+    const infinite_loop = customRendererFixture.infinite_loop_prevention;
+    it(infinite_loop.title, async () => {
+      const container = await AstroContainer.create();
+      const result = await container.renderToString(StoryblokRichText, {
+        props: {
+          document: infinite_loop.input,
+          components: {
+            heading: HeadingWithRichText,
+          },
+        },
+      });
+      expect(clean(result)).toBe(infinite_loop.expected);
+    });
   });
 });
diff --git a/packages/astro/tests/richtext/CustomText.astro b/packages/astro/tests/richtext/CustomText.astro
new file mode 100644
index 000000000..5ef3d15d0
--- /dev/null
+++ b/packages/astro/tests/richtext/CustomText.astro
@@ -0,0 +1,11 @@
+---
+import type { SbAstroRichTextProps } from '../../src/index';
+
+type Props = SbAstroRichTextProps<'text'>;
+
+const { text, context } = Astro.props;
+const data = context?.data as { prefix: string } | undefined;
+const prefix = data?.prefix ?? '';
+---
+
+{prefix} {text.toUpperCase()}
\ No newline at end of file
diff --git a/packages/astro/tests/richtext/HeadingWithRichText.astro b/packages/astro/tests/richtext/HeadingWithRichText.astro
new file mode 100644
index 000000000..f3e71fc28
--- /dev/null
+++ b/packages/astro/tests/richtext/HeadingWithRichText.astro
@@ -0,0 +1,18 @@
+---
+/**
+ * Custom heading component that internally uses StoryblokRichText.
+ * This tests the infinite loop prevention - without it, this would cause:
+ * HeadingWithRichText -> StoryblokRichText -> HeadingWithRichText -> ...
+ */
+import type { SbAstroRichTextProps } from '../../src/index';
+import StoryblokRichText from '../../src/components/StoryblokRichText.astro';
+
+type Props = SbAstroRichTextProps<'heading'>;
+
+const { attrs, content, context } = Astro.props;
+const Tag = `h${attrs?.level}`;
+---
+
+<Tag data-type="recursive-heading" data-level={attrs?.level}>
+  {content && <StoryblokRichText document={content} {...context} />}
+</Tag>
diff --git a/packages/astro/tests/vite-plugin-import-storyblok-components.test.ts b/packages/astro/tests/vite-plugin-import-storyblok-components.test.ts
new file mode 100644
index 000000000..a2dcbf388
--- /dev/null
+++ b/packages/astro/tests/vite-plugin-import-storyblok-components.test.ts
@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import { createComponentRegistrationParts, generateModuleCode } from '../src/vite-plugins/vite-plugin-import-storyblok-components';
+
+describe('vite-plugin-import-storyblok-components', () => {
+  describe('createComponentRegistrationParts', () => {
+    it('generates structured parts with wrapper for TDZ avoidance', () => {
+      const parts = createComponentRegistrationParts({
+        componentName: 'Card',
+        importPath: '/src/components/Card.astro',
+      });
+
+      expect(parts.importStatement).toBe(`import __Card_component__ from '/src/components/Card.astro';`);
+      expect(parts.wrapperDefinition).toBe(`const __Card_wrapper__ = { get default() { return __Card_component__; } };`);
+      expect(parts.registrationCall).toBe(`registerComponent('Card', __Card_wrapper__);`);
+    });
+
+    it('uses unique variable names based on component name', () => {
+      const cardParts = createComponentRegistrationParts({
+        componentName: 'Card',
+        importPath: '/src/Card.astro',
+      });
+      const heroParts = createComponentRegistrationParts({
+        componentName: 'Hero',
+        importPath: '/src/Hero.astro',
+      });
+
+      // Variable names should be unique per component
+      expect(cardParts.importStatement).toContain('__Card_component__');
+      expect(heroParts.importStatement).toContain('__Hero_component__');
+      expect(cardParts.wrapperDefinition).toContain('__Card_wrapper__');
+      expect(heroParts.wrapperDefinition).toContain('__Hero_wrapper__');
+    });
+  });
+
+  describe('generateModuleCode', () => {
+    it('generates valid module code without manual components', () => {
+      const code = generateModuleCode('/src/components', null, []);
+
+      expect(code).toContain('import { toCamelCase }');
+      expect(code).toContain('import.meta.glob');
+      expect(code).toContain('export { storyblokComponents }');
+    });
+
+    it('generates valid module code with manual components', () => {
+      const manualRegistrations = [
+        createComponentRegistrationParts({
+          componentName: 'card',
+          importPath: '/src/components/Card.astro',
+        }),
+        createComponentRegistrationParts({
+          componentName: 'hero',
+          importPath: '/src/components/Hero.astro',
+        }),
+      ];
+
+      const code = generateModuleCode('/src/components', null, manualRegistrations);
+
+      expect(code).toContain(`import __card_component__ from '/src/components/Card.astro'`);
+      expect(code).toContain(`const __card_wrapper__ = { get default() { return __card_component__; } }`);
+      expect(code).toContain(`registerComponent('card', __card_wrapper__)`);
+      expect(code).toContain(`import __hero_component__ from '/src/components/Hero.astro'`);
+      expect(code).toContain(`const __hero_wrapper__ = { get default() { return __hero_component__; } }`);
+      expect(code).toContain(`registerComponent('hero', __hero_wrapper__)`);
+    });
+
+    it('generates valid module code with fallback component', () => {
+      const fallbackRegistration = createComponentRegistrationParts({
+        componentName: 'FallbackComponent',
+        importPath: '@storyblok/astro/FallbackComponent.astro',
+      });
+
+      const code = generateModuleCode('/src/components', fallbackRegistration, []);
+
+      expect(code).toContain(`import __FallbackComponent_component__ from '@storyblok/astro/FallbackComponent.astro'`);
+      expect(code).toContain(`const __FallbackComponent_wrapper__ = { get default() { return __FallbackComponent_component__; } }`);
+      expect(code).toContain(`registerComponent('FallbackComponent', __FallbackComponent_wrapper__)`);
+    });
+
+    /**
+     * This test verifies that static imports are placed at the top of the module
+     * to ensure proper hoisting behavior and avoid TDZ issues.
+     */
+    it('places static imports at the top of the module', () => {
+      const manualRegistrations = [
+        createComponentRegistrationParts({
+          componentName: 'card',
+          importPath: '/src/components/Card.astro',
+        }),
+      ];
+
+      const code = generateModuleCode('/src/components', null, manualRegistrations);
+
+      // All imports should be at the top, before any other code
+      const toCamelCaseImportIndex = code.indexOf('import { toCamelCase }');
+      const cardImportIndex = code.indexOf('import __card_component__');
+      const modulesDefIndex = code.indexOf('const modules = import.meta.glob');
+
+      expect(toCamelCaseImportIndex).toBeGreaterThan(-1);
+      expect(cardImportIndex).toBeGreaterThan(-1);
+      expect(modulesDefIndex).toBeGreaterThan(-1);
+
+      // Both imports should come before the modules definition
+      expect(toCamelCaseImportIndex).toBeLessThan(modulesDefIndex);
+      expect(cardImportIndex).toBeLessThan(modulesDefIndex);
+    });
+
+    it('places wrapper definitions before registration calls', () => {
+      const manualRegistrations = [
+        createComponentRegistrationParts({
+          componentName: 'card',
+          importPath: '/src/components/Card.astro',
+        }),
+      ];
+
+      const code = generateModuleCode('/src/components', null, manualRegistrations);
+
+      // Wrapper definitions should come before registration calls
+      const wrapperDefIndex = code.indexOf('const __card_wrapper__');
+      const registerCallIndex = code.indexOf(`registerComponent('card', __card_wrapper__)`);
+
+      expect(wrapperDefIndex).toBeGreaterThan(-1);
+      expect(registerCallIndex).toBeGreaterThan(-1);
+      expect(wrapperDefIndex).toBeLessThan(registerCallIndex);
+    });
+
+    it('places registration calls after registerComponent is defined', () => {
+      const manualRegistrations = [
+        createComponentRegistrationParts({
+          componentName: 'card',
+          importPath: '/src/components/Card.astro',
+        }),
+      ];
+
+      const code = generateModuleCode('/src/components', null, manualRegistrations);
+
+      // registerComponent definition should come before registration calls
+      const registerComponentDefIndex = code.indexOf('const registerComponent = ');
+      const registerCallIndex = code.indexOf(`registerComponent('card'`);
+
+      expect(registerComponentDefIndex).toBeGreaterThan(-1);
+      expect(registerCallIndex).toBeGreaterThan(-1);
+      expect(registerComponentDefIndex).toBeLessThan(registerCallIndex);
+    });
+
+    it('uses glob pattern for auto-discovered components', () => {
+      const code = generateModuleCode('/src/components', null, []);
+
+      // Should use import.meta.glob for components in storyblok folder
+      expect(code).toContain(`import.meta.glob('/src/components/storyblok/**/*.astro'`);
+      expect(code).toContain('eager: true');
+    });
+
+    it('registers glob components before manual components', () => {
+      const manualRegistrations = [
+        createComponentRegistrationParts({
+          componentName: 'card',
+          importPath: '/src/components/Card.astro',
+        }),
+      ];
+
+      const code = generateModuleCode('/src/components', null, manualRegistrations);
+
+      // Glob components registration loop should come before manual registration
+      const globLoopIndex = code.indexOf('for (const filePath in modules)');
+      const manualRegisterIndex = code.indexOf(`registerComponent('card'`);
+
+      expect(globLoopIndex).toBeGreaterThan(-1);
+      expect(manualRegisterIndex).toBeGreaterThan(-1);
+      expect(globLoopIndex).toBeLessThan(manualRegisterIndex);
+    });
+
+    /**
+     * This test verifies that the TDZ fix is properly applied:
+     * components are registered with wrapper objects that use getters,
+     * not with the raw imported component reference.
+     */
+    it('registers components using wrapper with getter (TDZ fix)', () => {
+      const manualRegistrations = [
+        createComponentRegistrationParts({
+          componentName: 'card',
+          importPath: '/src/components/Card.astro',
+        }),
+      ];
+
+      const code = generateModuleCode('/src/components', null, manualRegistrations);
+
+      // Should NOT register with the raw component
+      expect(code).not.toContain(`registerComponent('card', __card_component__)`);
+
+      // Should register with the wrapper that has a getter
+      expect(code).toContain(`registerComponent('card', __card_wrapper__)`);
+
+      // The wrapper should use a getter to defer access
+      expect(code).toContain(`const __card_wrapper__ = { get default() { return __card_component__; } }`);
+    });
+  });
+});
diff --git a/packages/capi-client/package.json b/packages/capi-client/package.json
index dcad5cd0e..6e0cf5d8f 100644
--- a/packages/capi-client/package.json
+++ b/packages/capi-client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/api-client",
   "type": "module",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "private": false,
   "description": "Storyblok Content Delivery API Client",
   "author": "",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index a2fa8cfac..bfbed9ab7 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "storyblok",
   "type": "module",
-  "version": "4.18.2",
+  "version": "4.19.1",
   "description": "Storyblok CLI",
   "author": "Alvaro Saburido <hola@alvarosaburido.dev> (https://github.com/alvarosabu/)",
   "license": "MIT",
diff --git a/packages/cli/src/commands/assets/README.md b/packages/cli/src/commands/assets/README.md
index 942ac3c7c..ed550a453 100644
--- a/packages/cli/src/commands/assets/README.md
+++ b/packages/cli/src/commands/assets/README.md
@@ -4,8 +4,8 @@ The `assets` module provides tools to manage Storyblok assets and asset folders.
 
 ## Subcommands
 
-- [`pull`](./pull/README.md): Download assets from your Storyblok space.
-- [`push`](./push/README.md): Upload assets to your Storyblok space.
+- [`pull`](./pull/README.md): Download assets from your Storyblok space, and optionally from the organization's shared libraries.
+- [`push`](./push/README.md): Upload assets to your Storyblok space, or to the organization's shared libraries.
 
 > See each subcommand for detailed usage, options, and examples.
 
diff --git a/packages/cli/src/commands/assets/actions.ts b/packages/cli/src/commands/assets/actions.ts
index 0833459f1..fc41bc55b 100644
--- a/packages/cli/src/commands/assets/actions.ts
+++ b/packages/cli/src/commands/assets/actions.ts
@@ -3,9 +3,10 @@ import { getMapiClient } from '../../api';
 import { createPipelineBackpressureLock } from '../../utils/backpressure-lock';
 import { handleAPIError } from '../../utils/error/api-error';
 import { getResponseStatus, toError } from '../../utils/error/error';
+import { FetchError } from '../../utils/fetch';
 import { fetchAllPages } from '../../utils/pagination';
 import type { RegionCode } from '../../constants';
-import type { Asset, AssetFolderCreate, AssetFolderUpdate, AssetInternalTagsByName, AssetListQuery, AssetUpdate, AssetUpload } from './types';
+import type { Asset, AssetFolderCreate, AssetFolderUpdate, AssetInternalTagsByName, AssetListQuery, AssetUpdate, AssetUpload, SharedAssetFolderCreate, SharedAssetFolderUpdate, SharedInternalTagCreate } from './types';
 
 /**
  * Fetches a single page of assets from Storyblok Management API.
@@ -284,14 +285,14 @@ export const createAsset = async (
 };
 
 /**
- * Transfers a space-local asset into the org's global (shared) library.
+ * Transfers a space-local asset into the org's shared library.
  *
  * UX wording is "transfer"; the backend endpoint is still `convert`
  * (`AssetsServices::ConvertToSharedAsset`). Drop this mapping when the backend
- * ships the `convert` -> `transfer` rename. One-way only (space to org).
+ * ships the `convert` -> `transfer` rename. One-way only (space to shared).
  *
  * A 403 comes from the backend authorization policy (`AssetPolicy#convert?`):
- * the target folder must exist in the global asset library and the space must
+ * the target folder must exist in the shared asset library and the space must
  * have write access to it. Surface that as a friendly hint instead of a raw
  * API error.
  */
@@ -315,7 +316,7 @@ export const transferAsset = async (
       'transfer_asset',
       error,
       status === 403
-        ? `Not authorized to transfer into folder ${folderId}. Make sure it exists in the global asset library and that this space has write access to it.`
+        ? `Not authorized to transfer into folder ${folderId}. Make sure it exists in the shared asset library and that this space has write access to it.`
         : undefined,
     );
   }
@@ -329,7 +330,7 @@ export interface TransferResult {
 }
 
 /**
- * Transfers multiple assets into the global asset library, bounding in-flight
+ * Transfers multiple assets into the shared asset library, bounding in-flight
  * requests with the shared pipeline backpressure lock (2× the configured rate
  * limit), matching the throttle headroom used by the asset and story streams.
  * Per-asset errors are captured as failed results rather than aborting the
@@ -363,3 +364,222 @@ export const transferAssets = async (
     }
   }));
 };
+
+/**
+ * Fetches a page of shared (library) assets. `libraryId` is passed as the
+ * `in_folder` filter so only assets in that library are returned.
+ */
+export const fetchSharedAssets = async ({ spaceId, libraryId, params }: {
+  spaceId: string;
+  libraryId: number;
+  params?: AssetListQuery;
+}) => {
+  try {
+    const client = getMapiClient();
+    const { data, response } = await client.sharedAssets.list({
+      path: { space_id: Number(spaceId) },
+      query: { ...params, in_folder: libraryId, per_page: params?.per_page || 100, page: params?.page || 1 },
+      throwOnError: true,
+    });
+    const assets = (data?.assets || [])
+      .filter((asset): asset is Asset => Boolean(asset?.id && asset?.filename));
+
+    return { assets, headers: response.headers };
+  }
+  catch (maybeError) {
+    handleAPIError('pull_shared_assets', toError(maybeError));
+  }
+};
+
+/**
+ * Fetches the shared asset folders belonging to a library: the library root
+ * and all of its descendants.
+ */
+export const fetchSharedAssetFolders = async ({ spaceId, libraryId }: {
+  spaceId: string;
+  libraryId: number;
+}) => {
+  try {
+    const client = getMapiClient();
+    const { data } = await client.sharedAssetFolders.list({
+      path: { space_id: Number(spaceId) },
+      throwOnError: true,
+    });
+    const all = data?.shared_asset_folders || [];
+    // Index children by parent once, then walk down from the library root.
+    const childrenByParent = new Map<number, typeof all>();
+    for (const folder of all) {
+      if (folder.parent_id == null) {
+        continue;
+      }
+      const siblings = childrenByParent.get(folder.parent_id) ?? [];
+      siblings.push(folder);
+      childrenByParent.set(folder.parent_id, siblings);
+    }
+    const keep = new Set<number>([libraryId]);
+    const queue = [libraryId];
+    while (queue.length > 0) {
+      const parentId = queue.shift()!;
+      for (const child of childrenByParent.get(parentId) ?? []) {
+        if (!keep.has(child.id)) {
+          keep.add(child.id);
+          queue.push(child.id);
+        }
+      }
+    }
+    return { asset_folders: all.filter(folder => keep.has(folder.id)) };
+  }
+  catch (maybeError) {
+    handleAPIError('pull_shared_asset_folders', toError(maybeError));
+  }
+};
+
+export const createSharedAssetFolder = async (folder: SharedAssetFolderCreate, {
+  spaceId,
+}: {
+  spaceId: string;
+}) => {
+  try {
+    const client = getMapiClient();
+    const { data } = await client.sharedAssetFolders.create({
+      path: { space_id: Number(spaceId) },
+      body: { shared_asset_folder: folder },
+      throwOnError: true,
+    });
+    if (!data?.shared_asset_folder) {
+      throw new Error('Failed to create shared asset folder');
+    }
+    return data.shared_asset_folder;
+  }
+  catch (maybeError) {
+    handleAPIError('push_shared_asset_folder', toError(maybeError));
+  }
+};
+
+export const updateSharedAssetFolder = async (id: number, folder: SharedAssetFolderUpdate, {
+  spaceId,
+}: {
+  spaceId: string;
+}) => {
+  try {
+    await getMapiClient().sharedAssetFolders.update(id, {
+      path: { space_id: Number(spaceId) },
+      body: { shared_asset_folder: folder },
+      throwOnError: true,
+    });
+    return folder;
+  }
+  catch (maybeError) {
+    handleAPIError('push_shared_asset_folder', toError(maybeError));
+  }
+};
+
+// `getSharedAssetFolder`/`getSharedAsset` intentionally do NOT use the
+// `throwOnError`/`handleAPIError` pattern of the surrounding actions: callers
+// (upsert get-transports, referenced-asset resolution) treat a missing
+// resource as a normal "not found" and rely on `undefined`. We therefore
+// inspect `response.ok` by hand and only fail on non-404 errors.
+export const getSharedAssetFolder = async (folderId: number, { spaceId }: { spaceId: string }) => {
+  const { data, response } = await getMapiClient().sharedAssetFolders.get(folderId, {
+    path: { space_id: Number(spaceId) },
+  });
+  if (!response.ok && response.status !== 404) {
+    handleAPIError('pull_shared_asset_folder', new FetchError(response.statusText, response));
+  }
+  return data?.shared_asset_folder;
+};
+
+export const getSharedAsset = async (assetId: number, { spaceId }: { spaceId: string }) => {
+  const { data, response } = await getMapiClient().sharedAssets.get(assetId, {
+    path: { space_id: Number(spaceId) },
+  });
+  if (!response.ok && response.status !== 404) {
+    handleAPIError('pull_shared_asset', new FetchError(response.statusText, response));
+  }
+  return data;
+};
+
+export const createSharedAsset = async (
+  asset: AssetUpload,
+  fileBuffer: ArrayBuffer,
+  { spaceId }: { spaceId: string },
+): Promise<Asset> => {
+  try {
+    const client = getMapiClient();
+    // Strip `id` — it identifies the local/manifest asset for mapping and must
+    // not flow into the metadata update inside the create flow.
+    const { id: _id, ...assetBody } = asset;
+    return await client.sharedAssets.create({
+      body: assetBody,
+      file: fileBuffer,
+      path: { space_id: Number(spaceId) },
+    });
+  }
+  catch (maybeError) {
+    handleAPIError('push_shared_asset_create', toError(maybeError));
+  }
+};
+
+export const updateSharedAsset = async (
+  id: number,
+  asset: AssetUpdate & { short_filename?: string },
+  { spaceId, fileBuffer }: { spaceId: string; fileBuffer?: ArrayBuffer },
+): Promise<void> => {
+  try {
+    const client = getMapiClient();
+    const { short_filename, ...metadata } = asset;
+    if (fileBuffer !== undefined) {
+      if (!short_filename) {
+        throw new Error('short_filename is required when replacing an asset file');
+      }
+      await client.sharedAssets.update(id, {
+        path: { space_id: Number(spaceId) },
+        body: { asset: metadata, short_filename },
+        file: fileBuffer,
+      });
+    }
+    else {
+      await client.sharedAssets.update(id, {
+        path: { space_id: Number(spaceId) },
+        body: { asset: metadata },
+      });
+    }
+  }
+  catch (maybeError) {
+    handleAPIError('push_shared_asset_update', toError(maybeError));
+  }
+};
+
+export const fetchSharedInternalTags = async ({ spaceId, libraryId }: {
+  spaceId: string;
+  libraryId: number;
+}) => {
+  try {
+    const client = getMapiClient();
+    return await fetchAllPages(
+      (page: number) => client.sharedInternalTags.list({
+        path: { space_id: Number(spaceId) },
+        query: { asset_folder_id: libraryId, page },
+        throwOnError: true,
+      }),
+      data => data?.internal_tags ?? [],
+    );
+  }
+  catch (maybeError) {
+    handleAPIError('pull_shared_internal_tags', toError(maybeError));
+  }
+};
+
+export const createSharedInternalTag = async (tag: SharedInternalTagCreate, { spaceId }: { spaceId: string }) => {
+  try {
+    const { data } = await getMapiClient().sharedInternalTags.create({
+      path: { space_id: Number(spaceId) },
+      body: { shared_internal_tag: tag },
+      throwOnError: true,
+    });
+    return data?.internal_tag;
+  }
+  catch (maybeError) {
+    handleAPIError('push_shared_internal_tag', toError(maybeError));
+  }
+};
diff --git a/packages/cli/src/commands/assets/pipelines.ts b/packages/cli/src/commands/assets/pipelines.ts
index e1c4c9ac4..40722502b 100644
--- a/packages/cli/src/commands/assets/pipelines.ts
+++ b/packages/cli/src/commands/assets/pipelines.ts
@@ -17,6 +17,7 @@ import type {
   CreateAssetTransport,
   GetAssetFolderTransport,
   GetAssetTransport,
+  SharedTagResolver,
   UpdateAssetFolderTransport,
   UpdateAssetTransport,
 } from './streams';
@@ -33,6 +34,7 @@ export const upsertAssetFoldersPipeline = async ({
   maps,
   transports,
   ui,
+  skipRootFolders,
 }: {
   directoryPath: string;
   logger: Logger;
@@ -45,6 +47,7 @@ export const upsertAssetFoldersPipeline = async ({
     cleanupAssetFolder?: CleanupAssetFolderTransport;
   };
   ui: UI;
+  skipRootFolders?: boolean;
 }): Promise<Summaries> => {
   const folderProgress = ui.createProgressBar({ title: 'Folders...'.padEnd(PROGRESS_BAR_PADDING) });
   const summary = { total: 0, succeeded: 0, failed: 0 };
@@ -52,10 +55,15 @@ export const upsertAssetFoldersPipeline = async ({
   await pipeline(
     readLocalAssetFoldersStream({
       directoryPath,
+      skipRootFolders,
       setTotalFolders: (total) => {
         summary.total = total;
         folderProgress.setTotal(total);
       },
+      onFolderSkip: () => {
+        summary.total -= 1;
+        folderProgress.setTotal(summary.total);
+      },
       onFolderError: (error) => {
         summary.failed += 1;
         logOnlyError(error);
@@ -94,7 +102,7 @@ export const upsertAssetsPipeline = async ({
   assetData?: AssetUpload;
   directoryPath: string;
   logger: Logger;
-  maps: { assets: AssetMap; assetFolders: AssetFolderMap; assetInternalTagsByName?: AssetInternalTagsByName };
+  maps: { assets: AssetMap; assetFolders: AssetFolderMap; assetInternalTagsByName?: AssetInternalTagsByName; resolveSharedTagIds?: SharedTagResolver };
   transports: {
     getAsset: GetAssetTransport;
     createAsset: CreateAssetTransport;
diff --git a/packages/cli/src/commands/assets/pull/README.md b/packages/cli/src/commands/assets/pull/README.md
index 73f4f0812..733e6aa76 100644
--- a/packages/cli/src/commands/assets/pull/README.md
+++ b/packages/cli/src/commands/assets/pull/README.md
@@ -41,6 +41,7 @@ storyblok assets pull --space YOUR_SPACE_ID --asset-token YOUR_ASSET_TOKEN
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-s, --space <space>` | (Required) The ID of the space to pull assets from | - |
+| `--target <target>` | Pull source: `with-referenced`, `all`, `space`, or `shared` | `with-referenced` |
 | `-p, --path <path>` | Base path where assets are saved (assets are written to `<path>/assets/<space>`) | `.storyblok` |
 | `-d, --dry-run` | Preview changes without applying them to Storyblok | `false` |
 | `-q, --query <query>` | Filter assets using Storyblok filter query syntax (e.g., `--query="search=my-file.jpg&with_tags=tag1,tag2"`) | - |
diff --git a/packages/cli/src/commands/assets/pull/index.test.ts b/packages/cli/src/commands/assets/pull/index.test.ts
index 833a23c3b..b44d4fe1f 100644
--- a/packages/cli/src/commands/assets/pull/index.test.ts
+++ b/packages/cli/src/commands/assets/pull/index.test.ts
@@ -112,6 +112,51 @@ const preconditions = {
       }),
     );
   },
+  hasReadableLibraries(libraries: { id: number; name: string }[], onListed?: () => void) {
+    server.use(
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders', () => {
+        onListed?.();
+        return HttpResponse.json({
+          shared_asset_folders: libraries.map(library => ({
+            id: library.id,
+            name: library.name,
+            parent_id: null,
+            uuid: `u${library.id}`,
+            asset_folder_access: [{ space_id: 12345, access_level: 'read' }],
+          })),
+        });
+      }),
+    );
+  },
+  canFetchSharedAssetPages(assets: MockAsset[], onListed?: () => void) {
+    server.use(
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_assets', () => {
+        onListed?.();
+        return HttpResponse.json(
+          { assets },
+          { headers: { 'Total': String(assets.length), 'Per-Page': '100' } },
+        );
+      }),
+    );
+  },
+  sharedAssetResolves(asset: MockAsset) {
+    server.use(
+      http.get(`https://mapi.storyblok.com/v1/spaces/12345/shared_assets/${asset.id}`, () =>
+        HttpResponse.json(asset)),
+    );
+  },
+  hasLocalStoriesReferencing(assetIds: number[]) {
+    vol.fromJSON({
+      '.storyblok/stories/12345/home_uuid.json': JSON.stringify({
+        id: 1,
+        uuid: 'uuid',
+        content: {
+          component: 'page',
+          body: assetIds.map(id => ({ component: 'hero', image: { fieldtype: 'asset', id } })),
+        },
+      }),
+    });
+  },
 };
 
 describe('assets pull command', () => {
@@ -435,4 +480,85 @@ describe('assets pull command', () => {
     expect(logFile).toContain('"save":{"total":2,"succeeded":2,"failed":0}');
     expect(process.exitCode).toBe(0);
   });
+
+  describe('shared library targets', () => {
+    const writtenPaths = () => Object.keys(vol.toJSON()).map(p => p.replace(/\\/g, '/'));
+
+    it('pull --target=shared writes each readable library into shared/<id>/', async () => {
+      const libraryAsset = { id: 90, filename: 'https://a.storyblok.com/g/1/x.png', asset_folder_id: 7 };
+      preconditions.hasReadableLibraries([{ id: 7, name: 'Brand' }]);
+      preconditions.canFetchSharedAssetPages([libraryAsset]);
+      preconditions.canDownloadAssets([libraryAsset]);
+
+      await assetsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--target', 'shared']);
+
+      expect(writtenPaths().some(p => p.includes('assets/shared/7/x_90'))).toBe(true);
+      expect(process.exitCode).toBe(0);
+    });
+
+    it('pull --target=space makes no shared calls', async () => {
+      const sharedSpy = vi.fn();
+      preconditions.canFetchRemoteFolders([]);
+      preconditions.canFetchRemoteAssetPages([[makeMockAsset()]]);
+      preconditions.canDownloadAssets([makeMockAsset({ id: 1 })]);
+      preconditions.hasReadableLibraries([{ id: 7, name: 'Brand' }], sharedSpy);
+
+      await assetsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--target', 'space']);
+
+      expect(sharedSpy).not.toHaveBeenCalled();
+    });
+
+    it('pull --target=all writes both the space library and every readable library', async () => {
+      const spaceAsset = makeMockAsset();
+      const libraryAsset = { id: 90, filename: 'https://a.storyblok.com/g/1/x.png', asset_folder_id: 7 };
+      preconditions.canFetchRemoteFolders([]);
+      preconditions.canFetchRemoteAssetPages([[spaceAsset]]);
+      preconditions.canDownloadAssets([spaceAsset]);
+      preconditions.hasReadableLibraries([{ id: 7, name: 'Brand' }]);
+      preconditions.canFetchSharedAssetPages([libraryAsset]);
+      preconditions.canDownloadAssets([libraryAsset]);
+
+      await assetsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--target', 'all']);
+
+      expect(assetFileExists(spaceAsset)).toBeTruthy();
+      expect(writtenPaths().some(p => p.includes('assets/shared/7/x_90'))).toBe(true);
+    });
+
+    it('pull with-referenced pulls space assets and only referenced shared assets', async () => {
+      const spaceAsset = makeMockAsset({ id: 42 });
+      const sharedAsset = { id: 90, filename: 'https://a.storyblok.com/g/1/x.png', asset_folder_id: 7 };
+      preconditions.hasLocalStoriesReferencing([42, 90]);
+      preconditions.canFetchRemoteFolders([]);
+      preconditions.canFetchRemoteAssetPages([[spaceAsset]]);
+      preconditions.canDownloadAssets([spaceAsset]);
+      preconditions.sharedAssetResolves(sharedAsset);
+      preconditions.hasReadableLibraries([{ id: 7, name: 'Brand' }]);
+      preconditions.canDownloadAssets([sharedAsset]);
+
+      await assetsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345']);
+
+      expect(writtenPaths().some(p => p.includes('assets/shared/7/x_90'))).toBe(true);
+    });
+
+    it('pull with-referenced with no local stories makes no shared calls', async () => {
+      const sharedSpy = vi.fn();
+      preconditions.canFetchRemoteFolders([]);
+      preconditions.canFetchRemoteAssetPages([[makeMockAsset()]]);
+      preconditions.canDownloadAssets([makeMockAsset({ id: 1 })]);
+      preconditions.hasReadableLibraries([{ id: 7, name: 'Brand' }], sharedSpy);
+
+      await assetsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345']);
+
+      expect(sharedSpy).not.toHaveBeenCalled();
+    });
+
+    it('rejects an invalid --target value', async () => {
+      const pull = assetsCommand.commands.find(command => command.name() === 'pull')!;
+      pull.exitOverride();
+
+      await expect(
+        assetsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--target', 'bogus']),
+      ).rejects.toThrow(/Allowed choices/i);
+    });
+  });
 });
diff --git a/packages/cli/src/commands/assets/pull/index.ts b/packages/cli/src/commands/assets/pull/index.ts
index a39dd685a..4def08771 100644
--- a/packages/cli/src/commands/assets/pull/index.ts
+++ b/packages/cli/src/commands/assets/pull/index.ts
@@ -1,4 +1,7 @@
 import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { Option } from 'commander';
+import { Sema } from 'async-sema';
 import { colorPalette, commands, directories } from '../../../constants';
 import { assetsCommand } from '../command';
 import { getUI } from '../../../utils/ui';
@@ -13,19 +16,47 @@ import {
   downloadAssetStream,
   fetchAssetFoldersStream,
   fetchAssetsStream,
+  fetchSharedAssetFoldersStream,
+  fetchSharedAssetsStream,
   makeWriteAssetFolderFSTransport,
   makeWriteAssetFSTransport,
   writeAssetFolderStream,
   writeAssetStream,
 } from '../streams';
+import type { Asset } from '../types';
+import { getSharedAsset } from '../actions';
+import { buildLibraryRootResolver, listReadableLibraries, resolveScopeBaseDir, type Scope } from '../scope';
+import { collectReferencedAssetIds, readLocalStoryContents } from '../referenced';
+
+/**
+ * Pull source: assets referenced by local stories (default), everything, the
+ * space only, or the org's shared libraries only.
+ */
+const PULL_TARGETS = ['with-referenced', 'all', 'space', 'shared'] as const;
+type PullTarget = typeof PULL_TARGETS[number];
+
+interface PullSummary {
+  folderResults: { total: number; succeeded: number; failed: number };
+  fetchAssetPages: { total: number; succeeded: number; failed: number };
+  fetchAssets: { total: number; succeeded: number; failed: number };
+  save: { total: number; succeeded: number; failed: number };
+}
+
+const createSummary = (): PullSummary => ({
+  folderResults: { total: 0, succeeded: 0, failed: 0 },
+  fetchAssetPages: { total: 0, succeeded: 0, failed: 0 },
+  fetchAssets: { total: 0, succeeded: 0, failed: 0 },
+  save: { total: 0, succeeded: 0, failed: 0 },
+});
 
 const pullCmd = assetsCommand
   .command('pull')
   .option('-s, --space <space>', 'space ID')
+  .addOption(new Option('--target <target>', 'pull source: with-referenced | all | space | shared').choices(PULL_TARGETS).default('with-referenced'))
   .option('-d, --dry-run', 'Preview changes without applying them to Storyblok')
   .option('-q, --query <query>', 'Filter assets using Storyblok filter query syntax. Example: --query="search=my-file.jpg&with_tags=tag1,tag2"')
   .option('--asset-token <token>', 'Asset token for accessing private assets')
-  .description(`Download your space's assets as local files.`);
+  .description(`Download your space's assets, and optionally shared library assets, as local files.`);
 
 pullCmd
   .action(async (options, command) => {
@@ -55,47 +86,52 @@ pullCmd
     }
 
     const { region } = state;
-
-    const summary = {
-      folderResults: { total: 0, succeeded: 0, failed: 0 },
-      fetchAssetPages: { total: 0, succeeded: 0, failed: 0 },
-      fetchAssets: { total: 0, succeeded: 0, failed: 0 },
-      save: { total: 0, succeeded: 0, failed: 0 },
-    };
-
+    const target = (options.target as PullTarget) ?? 'with-referenced';
+    const params = options.query ? Object.fromEntries(new URLSearchParams(options.query)) : {};
+    const summary = createSummary();
     let fatalError = false;
 
-    try {
+    /** Pulls a full scope: its folders and all of its assets. */
+    const pullScopeFull = async (scope: Scope): Promise<Set<number>> => {
+      const directoryPath = resolveScopeBaseDir(scope, basePath);
+      const collectedIds = new Set<number>();
+
       const folderProgress = ui.createProgressBar({ title: 'Folders...'.padEnd(25) });
       const fetchAssetPagesProgress = ui.createProgressBar({ title: 'Fetching Asset Pages...'.padEnd(24) });
       const fetchAssetsProgress = ui.createProgressBar({ title: 'Fetching Assets...'.padEnd(24) });
       const saveProgress = ui.createProgressBar({ title: 'Saving Assets...'.padEnd(24) });
+
+      const folderHandlers = {
+        spaceId: space,
+        setTotalFolders: (total: number) => {
+          summary.folderResults.total += total;
+          folderProgress.setTotal(total);
+        },
+        onError: (error: Error) => {
+          summary.folderResults.failed += 1;
+          summary.folderResults.total = summary.folderResults.total || 1;
+          folderProgress.setTotal(summary.folderResults.total);
+          logOnlyError(error);
+        },
+      };
+      const foldersStream = scope.kind === 'library'
+        ? fetchSharedAssetFoldersStream({
+            ...folderHandlers,
+            libraryId: scope.libraryId,
+            onSuccess: () => logger.info('Fetched library folders', { libraryId: scope.libraryId }),
+          })
+        : fetchAssetFoldersStream({
+            ...folderHandlers,
+            onSuccess: () => logger.info('Fetched asset folders'),
+          });
+
       await pipeline(
-        fetchAssetFoldersStream({
-          spaceId: space,
-          setTotalFolders: (total) => {
-            summary.folderResults.total = total;
-            folderProgress.setTotal(total);
-          },
-          onSuccess: () => {
-            logger.info('Fetched asset folders');
-          },
-          onError: (error) => {
-            summary.folderResults.failed += 1;
-            summary.folderResults.total = summary.folderResults.total || 1;
-            folderProgress.setTotal(summary.folderResults.total);
-            logOnlyError(error);
-          },
-        }),
+        foldersStream,
         writeAssetFolderStream({
           writeAssetFolder: options.dryRun
             ? async folder => folder
-            : makeWriteAssetFolderFSTransport({
-                directoryPath: resolveCommandPath(directories.assets, space, basePath),
-              }),
-          onIncrement: () => {
-            folderProgress.increment();
-          },
+            : makeWriteAssetFolderFSTransport({ directoryPath }),
+          onIncrement: () => folderProgress.increment(),
           onFolderSuccess: (folder) => {
             logger.info('Saved folder', { folderId: folder.id });
             summary.folderResults.succeeded += 1;
@@ -107,40 +143,123 @@ pullCmd
           },
         }),
       );
+
+      // Capture per-scope bases so repeated setter calls assign (idempotent)
+      // within a scope while still accumulating across scopes.
+      const pagesBase = summary.fetchAssetPages.total;
+      const assetsBase = summary.fetchAssets.total;
+      const saveBase = summary.save.total;
+      const assetLabel = scope.kind === 'library' ? 'library assets' : 'assets';
+      const assetHandlers = {
+        spaceId: space,
+        params,
+        setTotalAssets: (total: number) => {
+          summary.fetchAssets.total = assetsBase + total;
+          summary.save.total = saveBase + total;
+          fetchAssetsProgress.setTotal(total);
+          saveProgress.setTotal(total);
+        },
+        setTotalPages: (totalPages: number) => {
+          summary.fetchAssetPages.total = pagesBase + totalPages;
+          fetchAssetPagesProgress.setTotal(totalPages);
+        },
+        onIncrement: () => fetchAssetPagesProgress.increment(),
+        onPageSuccess: (page: number, totalPages: number) => {
+          logger.info(`Fetched ${assetLabel} page ${page} of ${totalPages}`);
+          summary.fetchAssetPages.succeeded += 1;
+        },
+        onPageError: (error: Error, page: number, totalPages: number) => {
+          summary.fetchAssetPages.failed += 1;
+          logOnlyError(error, { page, totalPages });
+        },
+      };
+      const assetsStream = scope.kind === 'library'
+        ? fetchSharedAssetsStream({ ...assetHandlers, libraryId: scope.libraryId })
+        : fetchAssetsStream(assetHandlers);
+
       await pipeline(
-        fetchAssetsStream({
-          spaceId: space,
-          params: options.query ? Object.fromEntries(new URLSearchParams(options.query)) : {},
-          setTotalAssets: (total) => {
-            summary.fetchAssets.total = total;
-            summary.save.total = total;
-            fetchAssetsProgress.setTotal(total);
-            saveProgress.setTotal(total);
+        assetsStream,
+        downloadAssetStream({
+          assetToken,
+          region,
+          onIncrement: () => fetchAssetsProgress.increment(),
+          onAssetSuccess: (asset) => {
+            logger.info('Fetched asset', { assetId: asset.id });
+            collectedIds.add(asset.id);
+            summary.fetchAssets.succeeded += 1;
+          },
+          onAssetError: (error, asset) => {
+            summary.fetchAssets.failed += 1;
+            summary.save.total -= 1;
+            saveProgress.setTotal(summary.save.total);
+            logOnlyError(error, { assetId: asset.id });
           },
-          setTotalPages: (totalPages) => {
-            summary.fetchAssetPages.total = totalPages;
-            fetchAssetPagesProgress.setTotal(totalPages);
+        }),
+        writeAssetStream({
+          writeAsset: options.dryRun
+            ? async asset => asset
+            : makeWriteAssetFSTransport({ directoryPath }),
+          onIncrement: () => saveProgress.increment(),
+          onAssetSuccess: (asset) => {
+            logger.info('Saved asset', { assetId: asset.id });
+            summary.save.succeeded += 1;
           },
-          onIncrement: () => {
-            fetchAssetPagesProgress.increment();
+          onAssetError: (error, asset) => {
+            summary.save.failed += 1;
+            logOnlyError(error, { assetId: asset.id });
           },
-          onPageSuccess: (page, totalPages) => {
-            logger.info(`Fetched assets page ${page} of ${totalPages}`);
-            summary.fetchAssetPages.succeeded += 1;
+        }),
+      );
+
+      return collectedIds;
+    };
+
+    /**
+     * Pulls a specific set of already-resolved shared assets into their library
+     * subtree (used by `with-referenced`): pulls the library folders, then
+     * downloads only the referenced assets.
+     */
+    const pullReferencedAssets = async (libraryId: number, assets: Asset[]): Promise<void> => {
+      const scope: Scope = { kind: 'library', libraryId };
+      const directoryPath = resolveScopeBaseDir(scope, basePath);
+
+      const folderProgress = ui.createProgressBar({ title: 'Folders...'.padEnd(25) });
+      await pipeline(
+        fetchSharedAssetFoldersStream({
+          spaceId: space,
+          libraryId,
+          setTotalFolders: total => folderProgress.setTotal(total),
+          onError: error => logOnlyError(error),
+        }),
+        writeAssetFolderStream({
+          writeAssetFolder: options.dryRun
+            ? async folder => folder
+            : makeWriteAssetFolderFSTransport({ directoryPath }),
+          onIncrement: () => folderProgress.increment(),
+          onFolderSuccess: (folder) => {
+            summary.folderResults.total += 1;
+            summary.folderResults.succeeded += 1;
+            logger.info('Saved library folder', { folderId: folder.id });
           },
-          onPageError: (error, page, totalPages) => {
-            summary.fetchAssetPages.failed += 1;
-            logOnlyError(error, { page, totalPages });
+          onFolderError: (error, folder) => {
+            summary.folderResults.failed += 1;
+            logOnlyError(error, { folderId: folder.id });
           },
         }),
+      );
+
+      const saveProgress = ui.createProgressBar({ title: 'Saving Assets...'.padEnd(24) });
+      summary.fetchAssets.total += assets.length;
+      summary.save.total += assets.length;
+      saveProgress.setTotal(assets.length);
+
+      await pipeline(
+        Readable.from(assets),
         downloadAssetStream({
           assetToken,
           region,
-          onIncrement: () => {
-            fetchAssetsProgress.increment();
-          },
           onAssetSuccess: (asset) => {
-            logger.info('Fetched asset', { assetId: asset.id });
+            logger.info('Fetched library asset', { assetId: asset.id });
             summary.fetchAssets.succeeded += 1;
           },
           onAssetError: (error, asset) => {
@@ -153,14 +272,10 @@ pullCmd
         writeAssetStream({
           writeAsset: options.dryRun
             ? async asset => asset
-            : makeWriteAssetFSTransport({
-                directoryPath: resolveCommandPath(directories.assets, space, basePath),
-              }),
-          onIncrement: () => {
-            saveProgress.increment();
-          },
+            : makeWriteAssetFSTransport({ directoryPath }),
+          onIncrement: () => saveProgress.increment(),
           onAssetSuccess: (asset) => {
-            logger.info('Saved asset', { assetId: asset.id });
+            logger.info('Saved library asset', { assetId: asset.id });
             summary.save.succeeded += 1;
           },
           onAssetError: (error, asset) => {
@@ -169,13 +284,75 @@ pullCmd
           },
         }),
       );
+    };
+
+    try {
+      if (target === 'space') {
+        await pullScopeFull({ kind: 'space', spaceId: space });
+      }
+      else if (target === 'shared') {
+        const libraries = await listReadableLibraries(space);
+        for (const library of libraries) {
+          await pullScopeFull({ kind: 'library', libraryId: library.id });
+        }
+      }
+      else if (target === 'all') {
+        await pullScopeFull({ kind: 'space', spaceId: space });
+        const libraries = await listReadableLibraries(space);
+        for (const library of libraries) {
+          await pullScopeFull({ kind: 'library', libraryId: library.id });
+        }
+      }
+      else {
+        // with-referenced (default): pull the space, then resolve shared assets
+        // referenced by already-pulled local stories.
+        const spaceAssetIds = await pullScopeFull({ kind: 'space', spaceId: space });
+
+        const stories = await readLocalStoryContents(resolveCommandPath(directories.stories, space, basePath));
+        if (stories.length > 0) {
+          const referenced = collectReferencedAssetIds(stories);
+          for (const id of spaceAssetIds) {
+            referenced.delete(id);
+          }
+
+          if (referenced.size > 0) {
+            const lock = new Sema(12);
+            const resolved = await Promise.all(
+              [...referenced].map(async (id) => {
+                await lock.acquire();
+                try {
+                  return await getSharedAsset(id, { spaceId: space });
+                }
+                finally {
+                  lock.release();
+                }
+              }),
+            );
+            const sharedAssets = resolved.filter((asset): asset is Asset => Boolean(asset?.id));
+
+            if (sharedAssets.length > 0) {
+              const resolveRoot = await buildLibraryRootResolver(space);
+              const byLibrary = new Map<number, Asset[]>();
+              for (const asset of sharedAssets) {
+                const libraryId = resolveRoot(asset.asset_folder_id ?? 0);
+                const bucket = byLibrary.get(libraryId) ?? [];
+                bucket.push(asset);
+                byLibrary.set(libraryId, bucket);
+              }
+              for (const [libraryId, assets] of byLibrary) {
+                await pullReferencedAssets(libraryId, assets);
+              }
+            }
+          }
+        }
+      }
     }
     catch (maybeError) {
       fatalError = true;
       handleError(toError(maybeError));
     }
     finally {
-      logger.info('Pulling assets finished', summary);
+      logger.info('Pulling assets finished', { summary: { ...summary } });
       ui.stopAllProgressBars();
       const failedAssets = Math.max(summary.fetchAssets.failed, summary.save.failed);
       const folderSummary = {
diff --git a/packages/cli/src/commands/assets/push/README.md b/packages/cli/src/commands/assets/push/README.md
index ef2b5cff7..d62dbfaaa 100644
--- a/packages/cli/src/commands/assets/push/README.md
+++ b/packages/cli/src/commands/assets/push/README.md
@@ -72,5 +72,7 @@ storyblok assets push --space YOUR_SPACE_ID ./path/to/image.png \
 | `--data <data>` | Inline asset data as JSON (supports Asset fields, `metadata` maps to `meta_data`) | - |
 | `--short-filename <short-filename>` | Override the asset filename (defaults to the source filename) | - |
 | `--folder <folderId>` | Destination asset folder ID | - |
+| `--target <target>` | Push destination: `space`, `shared`, or `auto` (routes each local asset to its own space or shared library). A single-asset push accepts only `space` or `shared`. | `space` for a single asset, `auto` for a bulk push |
+| `--library <libraryId>` | Destination library ID. Required for a single-asset `--target=shared`, rejected with `--target=space` | - |
 | `--cleanup` | Delete local assets and metadata after a successful push | `false` |
 | `--update-stories` | Update file references in stories if necessary | `false` |
diff --git a/packages/cli/src/commands/assets/push/index.test.ts b/packages/cli/src/commands/assets/push/index.test.ts
index 2fb84f164..da3a587be 100644
--- a/packages/cli/src/commands/assets/push/index.test.ts
+++ b/packages/cli/src/commands/assets/push/index.test.ts
@@ -44,6 +44,7 @@ vi.spyOn(actions, 'createAsset');
 vi.spyOn(actions, 'updateAsset');
 vi.spyOn(actions, 'createAssetFolder');
 vi.spyOn(actions, 'updateAssetFolder');
+vi.spyOn(actions, 'createSharedAsset');
 vi.spyOn(storyActions, 'fetchStories');
 vi.spyOn(storyActions, 'updateStory');
 
@@ -63,6 +64,11 @@ const server = setupServer(
     { internal_tags: [] },
     { headers: { 'Total': '0', 'Per-Page': '100' } },
   )),
+  // A bulk push (default `--target auto`) lists shared libraries. Default to none;
+  // `preconditions.hasLibraries` overrides this for library-specific tests.
+  http.get('https://mapi.storyblok.com/v1/spaces/:spaceId/shared_asset_folders', () => HttpResponse.json(
+    { shared_asset_folders: [] },
+  )),
 );
 
 const preconditions = {
@@ -394,6 +400,65 @@ const preconditions = {
       [filePath]: content,
     });
   },
+  hasLibraries(libraries: { id: number; name: string; accessLevel: 'read' | 'write' }[], { space = DEFAULT_SPACE }: { space?: string } = {}) {
+    server.use(
+      http.get(`https://mapi.storyblok.com/v1/spaces/${space}/shared_asset_folders`, () =>
+        HttpResponse.json({
+          shared_asset_folders: libraries.map(library => ({
+            id: library.id,
+            name: library.name,
+            parent_id: null,
+            uuid: `u${library.id}`,
+            asset_folder_access: [{ space_id: Number(space), access_level: library.accessLevel }],
+          })),
+        })),
+    );
+  },
+  canUpsertSharedAssets(assets: MockAsset[], {
+    space = DEFAULT_SPACE,
+    libraryId = 7,
+  }: { space?: string; libraryId?: number } = {}) {
+    const sourceName = (asset: MockAsset) => asset.short_filename ?? basename(asset.filename);
+    const remoteAssets = assets.map(asset => ({
+      ...asset,
+      id: getID(),
+      filename: `https://a.storyblok.com/g/1/${sourceName(asset)}`,
+      asset_folder_id: asset.asset_folder_id ?? libraryId,
+    }));
+    server.use(
+      // Step 1: sign (shared uses query params for filename).
+      http.post(`https://mapi.storyblok.com/v1/spaces/${space}/shared_assets`, ({ request }) => {
+        const filename = new URL(request.url).searchParams.get('filename');
+        const index = assets.findIndex(asset => sourceName(asset) === filename);
+        if (index === -1) {
+          return HttpResponse.json({ message: 'Error uploading shared asset' }, { status: 500 });
+        }
+        return HttpResponse.json({
+          post_url: 'https://s3.amazonaws.com/a.storyblok.com',
+          fields: { key: `g/1/${filename}` },
+          id: remoteAssets[index].id,
+        });
+      }),
+      // Step 2: upload to S3 (generic).
+      http.post('https://s3.amazonaws.com/a.storyblok.com', async ({ request }) => {
+        const form = await request.formData();
+        return HttpResponse.json({ key: form.get('key') });
+      }),
+      // Step 3: finish upload.
+      http.get(`https://mapi.storyblok.com/v1/spaces/${space}/shared_assets/:assetId/finish_upload`, () =>
+        HttpResponse.json({ message: 'Upload finalized' })),
+      // Step 4: retrieve + metadata update target.
+      http.get(`https://mapi.storyblok.com/v1/spaces/${space}/shared_assets/:assetId`, ({ params }) => {
+        const match = remoteAssets.find(asset => String(asset.id) === String(params.assetId));
+        if (!match) {
+          return HttpResponse.json({ message: 'Asset not found' }, { status: 404 });
+        }
+        return HttpResponse.json(match);
+      }),
+      http.put(`https://mapi.storyblok.com/v1/spaces/${space}/shared_assets/:assetId`, () => HttpResponse.json({})),
+    );
+    return remoteAssets;
+  },
 };
 
 const parseManifest = async (space: string = DEFAULT_SPACE, basePath?: string) => {
@@ -490,6 +555,47 @@ describe('assets push command', () => {
     expect(process.exitCode).toBe(0);
   });
 
+  it('pushes from a non-numeric source directory (e.g. seed staging "qa-seed")', async () => {
+    const targetSpace = '54321';
+    const asset = makeMockAsset();
+    // Local source subtree keyed by a non-numeric directory name. The source identifier is a directory, not a space ID.
+    preconditions.canLoadAssets([asset], { space: 'qa-seed' });
+    preconditions.canUpsertRemoteAssets([asset], { space: targetSpace });
+
+    await assetsCommand.parseAsync(['node', 'test', 'push', '--from', 'qa-seed', '--space', targetSpace]);
+
+    expect(console.info).toHaveBeenCalledWith(expect.stringContaining('Push results: 1 processed, 0 assets failed'));
+    expect(process.exitCode).toBe(0);
+  });
+
+  it('should carry the dimensions segment from the source filename into the create payload as `size`', async () => {
+    const targetSpace = '54321';
+    const asset = makeMockAsset({ filename: `https://a.storyblok.com/f/${DEFAULT_SPACE}/2048x1820/7fb286a4c5/photo.jpg` });
+    preconditions.canLoadAssets([asset]);
+    preconditions.canUpsertRemoteAssets([asset], { space: targetSpace });
+
+    await assetsCommand.parseAsync(['node', 'test', 'push', '--from', DEFAULT_SPACE, '--space', targetSpace]);
+
+    expect(actions.createAsset).toHaveBeenCalledWith(expect.objectContaining({
+      size: '2048x1820',
+    }), expect.anything(), expect.anything());
+  });
+
+  it('should not set `size` when the source filename has no dimensions segment', async () => {
+    const targetSpace = '54321';
+    const asset = makeMockAsset({ filename: `https://a.storyblok.com/f/${DEFAULT_SPACE}/7fb286a4c5/photo.jpg` });
+    preconditions.canLoadAssets([asset]);
+    preconditions.canUpsertRemoteAssets([asset], { space: targetSpace });
+
+    await assetsCommand.parseAsync(['node', 'test', 'push', '--from', DEFAULT_SPACE, '--space', targetSpace]);
+
+    expect(actions.createAsset).toHaveBeenCalledWith(
+      expect.not.objectContaining({ size: expect.anything() }),
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
   it('should correctly resolve parent IDs even when child folders precede parents', async () => {
     const targetSpace = '54321';
     const numPairs = 10;
@@ -1592,4 +1698,281 @@ describe('assets push command', () => {
     );
     expect(process.exitCode).not.toBe(1);
   });
+
+  describe('shared library targets', () => {
+    it('pushes a single asset to a library (--target shared --library)', async () => {
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([makeMockAsset({ short_filename: 'hero.png', filename: 'hero.png' })], { libraryId: 7 });
+      preconditions.canLoadLocalFile('./hero.png', 'binary-content');
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', './hero.png', '--space', DEFAULT_SPACE, '--target', 'shared', '--library', '7']);
+
+      // Without --folder, the asset folder must default to the library root,
+      // otherwise shared-asset creation 403s.
+      expect(actions.createSharedAsset).toHaveBeenCalledWith(
+        expect.objectContaining({ asset_folder_id: 7 }),
+        expect.anything(),
+        expect.anything(),
+      );
+      expect(process.exitCode).toBe(0);
+    });
+
+    it('defaults a bulk shared-asset folder to the library root when the sidecar omits it', async () => {
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([makeMockAsset({ short_filename: 'x.png', filename: 'x.png' })], { libraryId: 7 });
+      const dir = resolveCommandPath(directories.assets, join('shared', '7'));
+      vol.fromJSON({
+        [join(dir, 'x_2.png')]: 'binary',
+        [join(dir, 'x_2.json')]: JSON.stringify({ id: 2, short_filename: 'x.png', filename: 'x.png' }),
+      });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(actions.createSharedAsset).toHaveBeenCalledWith(
+        expect.objectContaining({ asset_folder_id: 7 }),
+        expect.anything(),
+        expect.anything(),
+      );
+    });
+
+    it('rejects a single-asset --target shared without --library', async () => {
+      preconditions.canLoadLocalFile('./hero.png', 'binary-content');
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', './hero.png', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(actions.createSharedAsset).not.toHaveBeenCalled();
+      expect(process.exitCode).toBe(2);
+    });
+
+    it('rejects a single-asset --target auto', async () => {
+      preconditions.canLoadLocalFile('./hero.png', 'binary-content');
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', './hero.png', '--space', DEFAULT_SPACE, '--target', 'auto']);
+
+      expect(actions.createAsset).not.toHaveBeenCalled();
+      expect(actions.createSharedAsset).not.toHaveBeenCalled();
+      expect(process.exitCode).toBe(2);
+    });
+
+    it('rejects an invalid --target value', async () => {
+      const push = assetsCommand.commands.find(command => command.name() === 'push')!;
+      push.exitOverride();
+
+      await expect(
+        assetsCommand.parseAsync(['node', 'test', 'push', './hero.png', '--space', DEFAULT_SPACE, '--target', 'bogus']),
+      ).rejects.toThrow(/Allowed choices/i);
+    });
+
+    it('rejects --library combined with --target space', async () => {
+      preconditions.canLoadLocalFile('./hero.png', 'binary-content');
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', './hero.png', '--space', DEFAULT_SPACE, '--target', 'space', '--library', '7']);
+
+      expect(actions.createSharedAsset).not.toHaveBeenCalled();
+      expect(process.exitCode).toBe(2);
+    });
+
+    it('fails fast pushing to a read-only library', async () => {
+      preconditions.hasLibraries([{ id: 8, name: 'Locked', accessLevel: 'read' }]);
+      preconditions.canLoadLocalFile('./hero.png', 'binary-content');
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', './hero.png', '--space', DEFAULT_SPACE, '--target', 'shared', '--library', '8']);
+
+      expect(actions.createSharedAsset).not.toHaveBeenCalled();
+      expect(process.exitCode).toBe(2);
+      expect(getLogFileContents(LOG_PREFIX)).toMatch(/Locked/);
+    });
+
+    it('bulk push without --target defaults to auto (space subtree + each writable library)', async () => {
+      const spaceAsset = makeMockAsset({ short_filename: 'space.png' });
+      const libraryAsset = makeMockAsset({ short_filename: 'lib.png' });
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canLoadAssets([spaceAsset]);
+      preconditions.canLoadAssets([libraryAsset], { space: join('shared', '7') });
+      preconditions.canUpsertRemoteAssets([spaceAsset]);
+      preconditions.canUpsertSharedAssets([libraryAsset], { libraryId: 7 });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE]);
+
+      const written = Object.keys(vol.toJSON()).map(p => p.replace(/\\/g, '/'));
+      expect(written.some(p => p.includes('assets/12345/manifest.jsonl'))).toBe(true);
+      expect(written.some(p => p.includes('assets/shared/7/manifest.jsonl'))).toBe(true);
+    });
+
+    it('bulk --target=auto processes the space subtree and each writable library', async () => {
+      const spaceAsset = makeMockAsset({ short_filename: 'space.png' });
+      const libraryAsset = makeMockAsset({ short_filename: 'lib.png' });
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canLoadAssets([spaceAsset]);
+      preconditions.canLoadAssets([libraryAsset], { space: join('shared', '7') });
+      preconditions.canUpsertRemoteAssets([spaceAsset]);
+      preconditions.canUpsertSharedAssets([libraryAsset], { libraryId: 7 });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'auto']);
+
+      const written = Object.keys(vol.toJSON()).map(p => p.replace(/\\/g, '/'));
+      expect(written.some(p => p.includes('assets/12345/manifest.jsonl'))).toBe(true);
+      expect(written.some(p => p.includes('assets/shared/7/manifest.jsonl'))).toBe(true);
+    });
+
+    it('skips the library root folder on bulk push, still pushes child folders', async () => {
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([], { libraryId: 7 });
+      let rootFolderTouched = false;
+      let childFolderCreated = false;
+      server.use(
+        // The root (library) folder exists server-side; updating it from a
+        // space 403s. The child folder does not exist yet (create path).
+        http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders/7', () => {
+          rootFolderTouched = true;
+          return HttpResponse.json({ shared_asset_folder: { id: 7, name: 'Brand', parent_id: null } });
+        }),
+        http.put('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders/7', () => {
+          rootFolderTouched = true;
+          return HttpResponse.json({ message: 'Cannot update shared root asset folder in space context' }, { status: 403 });
+        }),
+        http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders/8', () =>
+          HttpResponse.json({ message: 'not found' }, { status: 404 })),
+        http.post('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders', async ({ request }) => {
+          childFolderCreated = true;
+          const body = await request.json() as { shared_asset_folder: { name: string; parent_id?: number } };
+          return HttpResponse.json({ shared_asset_folder: { id: 80, name: body.shared_asset_folder.name, parent_id: body.shared_asset_folder.parent_id } });
+        }),
+      );
+      const dir = resolveCommandPath(directories.assets, join('shared', '7'));
+      vol.fromJSON({
+        [join(dir, 'folders', 'Brand_7.json')]: JSON.stringify({ id: 7, name: 'Brand', parent_id: null, uuid: 'u7' }),
+        [join(dir, 'folders', 'Sub_8.json')]: JSON.stringify({ id: 8, name: 'Sub', parent_id: 7, uuid: 'u8' }),
+      });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(rootFolderTouched).toBe(false);
+      expect(childFolderCreated).toBe(true);
+      expect(process.exitCode).toBe(0);
+    });
+
+    it('updates an existing child library folder with only whitelisted fields', async () => {
+      // A pull→push round-trip writes child sidecars carrying their id and the
+      // org-managed `asset_folder_access`/`regions`. The space may update such a
+      // folder, but only its name/parent — forwarding the access grant 403s.
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([], { libraryId: 7 });
+      let updatePayload: Record<string, unknown> | undefined;
+      server.use(
+        // Child folder 8 already exists server-side → the push takes the update path.
+        http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders/8', () =>
+          HttpResponse.json({ shared_asset_folder: { id: 8, name: 'Sub', parent_id: 7 } })),
+        http.put('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders/8', async ({ request }) => {
+          updatePayload = ((await request.json()) as { shared_asset_folder: Record<string, unknown> }).shared_asset_folder;
+          // The backend rejects org-managed fields from space context.
+          if ('asset_folder_access' in updatePayload) {
+            return HttpResponse.json({ message: 'Forbidden' }, { status: 403 });
+          }
+          return new HttpResponse(null, { status: 204 });
+        }),
+      );
+      const dir = resolveCommandPath(directories.assets, join('shared', '7'));
+      vol.fromJSON({
+        [join(dir, 'folders', 'Brand_7.json')]: JSON.stringify({ id: 7, name: 'Brand', parent_id: null, uuid: 'u7', asset_folder_access: [{ space_id: 12345, access_level: 'write' }], regions: ['eu'] }),
+        [join(dir, 'folders', 'Sub_8.json')]: JSON.stringify({ id: 8, name: 'Sub', parent_id: 7, uuid: 'u8', asset_folder_access: [{ space_id: 12345, access_level: 'write' }], regions: [] }),
+      });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(updatePayload).toEqual({ name: 'Sub', parent_id: 7 });
+      expect(process.exitCode).toBe(0);
+    });
+
+    it('round-trips meta_data for a shared asset', async () => {
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([makeMockAsset({ short_filename: 'x.png', filename: 'x.png' })], { libraryId: 7 });
+      let capturedPut: { asset?: { meta_data?: unknown; internal_tag_ids?: string[] } } | undefined;
+      server.use(http.put('https://mapi.storyblok.com/v1/spaces/12345/shared_assets/:assetId', async ({ request }) => {
+        capturedPut = await request.json() as typeof capturedPut;
+        return HttpResponse.json({});
+      }));
+      const dir = resolveCommandPath(directories.assets, join('shared', '7'));
+      vol.fromJSON({
+        [join(dir, 'x_2.png')]: 'binary',
+        [join(dir, 'x_2.json')]: JSON.stringify({ id: 2, short_filename: 'x.png', filename: 'x.png', meta_data: { credit: 'ACME' } }),
+      });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(capturedPut?.asset?.meta_data).toEqual({ credit: 'ACME' });
+    });
+
+    it('creates missing library tags and remaps internal_tag_ids on push', async () => {
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([makeMockAsset({ short_filename: 'x.png', filename: 'x.png' })], { libraryId: 7 });
+      let capturedPut: { asset?: { internal_tag_ids?: string[] } } | undefined;
+      server.use(
+        http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_internal_tags', () => HttpResponse.json({ internal_tags: [] })),
+        http.post('https://mapi.storyblok.com/v1/spaces/12345/shared_internal_tags', () => HttpResponse.json({ internal_tag: { id: 500, name: 'hero', object_type: 'asset' } })),
+        http.put('https://mapi.storyblok.com/v1/spaces/12345/shared_assets/:assetId', async ({ request }) => {
+          capturedPut = await request.json() as typeof capturedPut;
+          return HttpResponse.json({});
+        }),
+      );
+      const dir = resolveCommandPath(directories.assets, join('shared', '7'));
+      vol.fromJSON({
+        [join(dir, 'x_2.png')]: 'binary',
+        [join(dir, 'x_2.json')]: JSON.stringify({ id: 2, short_filename: 'x.png', filename: 'x.png', internal_tag_ids: ['300'], internal_tags_list: [{ id: 300, name: 'hero' }] }),
+      });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(capturedPut?.asset?.internal_tag_ids).toEqual(['500']);
+    });
+
+    it('paginates shared library tags so a match on a later page is reused, not recreated', async () => {
+      preconditions.hasLibraries([{ id: 7, name: 'Brand', accessLevel: 'write' }]);
+      preconditions.canUpsertSharedAssets([makeMockAsset({ short_filename: 'x.png', filename: 'x.png' })], { libraryId: 7 });
+      let capturedPut: { asset?: { internal_tag_ids?: string[] } } | undefined;
+      let createCalled = false;
+      server.use(
+        // Two pages of existing library tags; the match lives on page 2. With one
+        // unpaginated request only page 1 is seen and the tag is wrongly recreated.
+        http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_internal_tags', ({ request }) => {
+          const page = new URL(request.url).searchParams.get('page');
+          const tags = page === '2'
+            ? [{ id: 999, name: 'hero', object_type: 'asset' }]
+            : [{ id: 100, name: 'other', object_type: 'asset' }];
+          return HttpResponse.json({ internal_tags: tags }, { headers: { 'Total': '2', 'Per-Page': '1' } });
+        }),
+        http.post('https://mapi.storyblok.com/v1/spaces/12345/shared_internal_tags', () => {
+          createCalled = true;
+          return HttpResponse.json({ internal_tag: { id: 500, name: 'hero', object_type: 'asset' } });
+        }),
+        http.put('https://mapi.storyblok.com/v1/spaces/12345/shared_assets/:assetId', async ({ request }) => {
+          capturedPut = await request.json() as typeof capturedPut;
+          return HttpResponse.json({});
+        }),
+      );
+      const dir = resolveCommandPath(directories.assets, join('shared', '7'));
+      vol.fromJSON({
+        [join(dir, 'x_2.png')]: 'binary',
+        [join(dir, 'x_2.json')]: JSON.stringify({ id: 2, short_filename: 'x.png', filename: 'x.png', internal_tag_ids: ['300'], internal_tags_list: [{ id: 300, name: 'hero' }] }),
+      });
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'shared']);
+
+      expect(capturedPut?.asset?.internal_tag_ids).toEqual(['999']);
+      expect(createCalled).toBe(false);
+    });
+
+    it('bulk --target=space ignores shared subtrees', async () => {
+      const spaceAsset = makeMockAsset({ short_filename: 'space.png' });
+      const libraryAsset = makeMockAsset({ short_filename: 'lib.png' });
+      preconditions.canLoadAssets([spaceAsset]);
+      preconditions.canLoadAssets([libraryAsset], { space: join('shared', '7') });
+      preconditions.canUpsertRemoteAssets([spaceAsset]);
+
+      await assetsCommand.parseAsync(['node', 'test', 'push', '--space', DEFAULT_SPACE, '--target', 'space']);
+
+      const written = Object.keys(vol.toJSON()).map(p => p.replace(/\\/g, '/'));
+      expect(written.some(p => p.includes('assets/shared/7/manifest.jsonl'))).toBe(false);
+    });
+  });
 });
diff --git a/packages/cli/src/commands/assets/push/index.ts b/packages/cli/src/commands/assets/push/index.ts
index 50259ed61..5d7ae3cec 100644
--- a/packages/cli/src/commands/assets/push/index.ts
+++ b/packages/cli/src/commands/assets/push/index.ts
@@ -1,4 +1,5 @@
 import { basename, join } from 'pathe';
+import { Option } from 'commander';
 import { colorPalette, commands, directories } from '../../../constants';
 import { assetsCommand } from '../command';
 import { getUI } from '../../../utils/ui';
@@ -16,18 +17,63 @@ import {
   makeCleanupAssetFSTransport,
   makeCreateAssetAPITransport,
   makeCreateAssetFolderAPITransport,
+  makeCreateSharedAssetAPITransport,
+  makeCreateSharedAssetFolderAPITransport,
   makeGetAssetAPITransport,
   makeGetAssetFolderAPITransport,
+  makeGetSharedAssetAPITransport,
+  makeGetSharedAssetFolderAPITransport,
+  makeSharedTagResolver,
   makeUpdateAssetAPITransport,
   makeUpdateAssetFolderAPITransport,
+  makeUpdateSharedAssetAPITransport,
+  makeUpdateSharedAssetFolderAPITransport,
 } from '../streams';
 import { createAssetInternalTag, fetchAssetInternalTagsByName } from '../actions';
-import type { Asset, AssetFolder, AssetFolderCreate, AssetFolderUpdate, AssetMapped, AssetUpload, UnmappedAssetInternalTag } from '../types';
+import type { Asset, AssetFolder, AssetFolderCreate, AssetFolderUpdate, AssetMap, AssetMapped, AssetUpload, UnmappedAssetInternalTag } from '../types';
 import { collectAssetInternalTagNames, ensureAssetInternalTags, internalTagNamesFromAssets, isRemoteSource, loadAssetFolderMap, loadAssetMap, loadSidecarAssetData, parseAssetData } from '../utils';
 import { findComponentSchemas } from '../../stories/utils';
 import { mapAssetReferencesInStoriesPipeline, upsertAssetFoldersPipeline, upsertAssetsPipeline } from '../pipelines';
 import type { Story } from '../../stories/constants';
 import { makeWriteStoryAPITransport } from '../../stories/streams';
+import { assertLibraryWritable, listWritableLibraries, resolveScopeBaseDir, type Scope } from '../scope';
+
+type Summaries = [string, Report['summary'][string]][];
+
+/** Push destination: the space, the org's shared libraries, or both. */
+const PUSH_TARGETS = ['space', 'shared', 'auto'] as const;
+type PushTarget = typeof PUSH_TARGETS[number];
+
+interface ScopeTransports {
+  getAsset: ReturnType<typeof makeGetAssetAPITransport>;
+  createAsset: ReturnType<typeof makeCreateAssetAPITransport>;
+  updateAsset: ReturnType<typeof makeUpdateAssetAPITransport>;
+  getAssetFolder: ReturnType<typeof makeGetAssetFolderAPITransport>;
+  createAssetFolder: ReturnType<typeof makeCreateAssetFolderAPITransport>;
+  updateAssetFolder: ReturnType<typeof makeUpdateAssetFolderAPITransport>;
+}
+
+/** Builds the API transport set for a scope. `apiSpace` is the active space. */
+function buildScopeTransports(scope: Scope, apiSpace: string): ScopeTransports {
+  if (scope.kind === 'library') {
+    return {
+      getAsset: makeGetSharedAssetAPITransport({ spaceId: apiSpace }),
+      createAsset: makeCreateSharedAssetAPITransport({ spaceId: apiSpace }),
+      updateAsset: makeUpdateSharedAssetAPITransport({ spaceId: apiSpace }),
+      getAssetFolder: makeGetSharedAssetFolderAPITransport({ spaceId: apiSpace }),
+      createAssetFolder: makeCreateSharedAssetFolderAPITransport({ spaceId: apiSpace }),
+      updateAssetFolder: makeUpdateSharedAssetFolderAPITransport({ spaceId: apiSpace }),
+    };
+  }
+  return {
+    getAsset: makeGetAssetAPITransport({ spaceId: apiSpace }),
+    createAsset: makeCreateAssetAPITransport({ spaceId: apiSpace }),
+    updateAsset: makeUpdateAssetAPITransport({ spaceId: apiSpace }),
+    getAssetFolder: makeGetAssetFolderAPITransport({ spaceId: apiSpace }),
+    createAssetFolder: makeCreateAssetFolderAPITransport({ spaceId: apiSpace }),
+    updateAssetFolder: makeUpdateAssetFolderAPITransport({ spaceId: apiSpace }),
+  };
+}
 
 const pushCmd = assetsCommand
   .command('push')
@@ -37,10 +83,12 @@ const pushCmd = assetsCommand
   .option('--data <data>', 'inline asset data as JSON')
   .option('--short-filename <short-filename>', 'override the asset filename')
   .option('--folder <folderId>', 'destination asset folder ID')
+  .addOption(new Option('--target <target>', 'push destination: space | shared | auto (default: space for a single asset, auto for a bulk push)').choices(PUSH_TARGETS))
+  .option('--library <libraryId>', 'destination library ID (required for single-asset --target=shared)')
   .option('--cleanup', 'delete local assets and metadata after a successful push (note: does not cleanup manifests)')
   .option('--update-stories', 'update file references in stories if necessary', false)
   .option('-d, --dry-run', 'Preview changes without applying them to Storyblok')
-  .description(`Push local assets to a Storyblok space.`);
+  .description(`Push local assets to a Storyblok space or shared library.`);
 
 pushCmd
   .action(async (assetInput, options, command) => {
@@ -70,179 +118,280 @@ pushCmd
       return;
     }
 
-    const summaries: [string, Report['summary'][string]][] = [];
-    let fatalError = false;
+    const libraryId = options.library ? Number(options.library) : undefined;
+    const assetBinaryPath = typeof assetInput === 'string' && assetInput.trim().length > 0
+      ? assetInput
+      : undefined;
+    // Default the destination by mode: a single asset has exactly one
+    // destination (the space), while a bulk push sends every local source to
+    // its destination (the space subtree plus every writable shared library).
+    // When nothing shared exists on disk, `auto` behaves exactly like `space`,
+    // so the default never writes to a library the user did not pull from.
+    const target = (options.target as PushTarget | undefined) ?? (assetBinaryPath ? 'space' : 'auto');
 
-    const manifestFile = join(resolveCommandPath(directories.assets, fromSpace, basePath), 'manifest.jsonl');
-    const folderManifestFile = join(resolveCommandPath(directories.assets, fromSpace, basePath), 'folders', 'manifest.jsonl');
+    // Validate the target/library combination for single-asset pushes.
+    if (assetBinaryPath) {
+      if (target === 'auto') {
+        // A single asset has exactly one destination; `auto` would silently
+        // fall back to space-only, so require an explicit target instead.
+        handleError(new CommandError('Pushing a single asset requires --target=space or --target=shared, not --target=auto.'), verbose);
+        process.exitCode = 2;
+        return;
+      }
+      if (target === 'shared' && !libraryId) {
+        handleError(new CommandError('Pushing a single asset to a library requires --library YOUR_LIBRARY_ID.'), verbose);
+        process.exitCode = 2;
+        return;
+      }
+      if (target === 'space' && libraryId) {
+        handleError(new CommandError('--library cannot be combined with --target=space.'), verbose);
+        process.exitCode = 2;
+        return;
+      }
+    }
 
+    // Resolve the list of scopes to process, then fail fast on read-only
+    // libraries before any writes happen.
+    let scopes: Scope[] = [];
     try {
-      const [assetMap, assetFolderMap] = await Promise.all([
-        loadAssetMap(manifestFile),
-        loadAssetFolderMap(folderManifestFile),
-      ]);
-      const maps = { assets: assetMap, assetFolders: assetFolderMap };
-      const assetsDirectoryPath = resolveCommandPath(directories.assets, fromSpace, basePath);
+      if (assetBinaryPath) {
+        if (target === 'shared') {
+          // Single-asset library push: the target library is explicit, so
+          // validate write access up front before any upload.
+          await assertLibraryWritable(targetSpace, libraryId!);
+          scopes = [{ kind: 'library', libraryId: libraryId! }];
+        }
+        else {
+          scopes = [{ kind: 'space', spaceId: fromSpace }];
+        }
+      }
+      else {
+        if (target === 'space' || target === 'auto') {
+          scopes.push({ kind: 'space', spaceId: fromSpace });
+        }
+        if (target === 'shared' || target === 'auto') {
+          // `listWritableLibraries` already filters to writable libraries, so
+          // these scopes need no further access check.
+          const libraries = await listWritableLibraries(targetSpace);
+          scopes.push(...libraries.map(library => ({ kind: 'library', libraryId: library.id }) satisfies Scope));
+        }
+      }
+    }
+    catch (maybeError) {
+      handleError(toError(maybeError), verbose);
+      process.exitCode = 2;
+      return;
+    }
 
-      /**
-       * Upsert Asset Folders
-       */
-      const assetFolderGetTransport = makeGetAssetFolderAPITransport({ spaceId: targetSpace });
-      const assetFolderCreateTransport = options.dryRun
-        ? async (folder: AssetFolderCreate) => folder as AssetFolder
-        : makeCreateAssetFolderAPITransport({ spaceId: targetSpace });
-      const assetFolderUpdateTransport = options.dryRun
-        ? async (_id: number, folder: AssetFolderUpdate) => folder
-        : makeUpdateAssetFolderAPITransport({ spaceId: targetSpace });
-      const assetFolderManifestTransport = options.dryRun
-        ? () => Promise.resolve()
-        : makeAppendAssetFolderManifestFSTransport({ manifestFile: folderManifestFile });
-      const cleanupAssetFolderTransport = options.cleanup && !options.dryRun
-        ? makeCleanupAssetFolderFSTransport()
-        : () => Promise.resolve();
+    const summaries: Summaries = [];
+    let fatalError = false;
+    let spaceAssetMap: AssetMap | undefined;
+    let spaceManifestFile: string | undefined;
 
-      summaries.push(...await upsertAssetFoldersPipeline({
-        directoryPath: join(assetsDirectoryPath, 'folders'),
-        logger,
-        maps,
-        transports: {
-          getAssetFolder: assetFolderGetTransport,
-          createAssetFolder: assetFolderCreateTransport,
-          updateAssetFolder: assetFolderUpdateTransport,
-          appendAssetFolderManifest: assetFolderManifestTransport,
-          cleanupAssetFolder: cleanupAssetFolderTransport,
-        },
-        ui,
-      }));
+    // Prepare single-asset upload data once (shared by whichever scope runs it).
+    let assetData: AssetUpload | undefined;
+    if (assetBinaryPath) {
+      const assetDataPartial = options.data
+        ? parseAssetData(options.data)
+        : !isRemoteSource(assetBinaryPath)
+            ? await loadSidecarAssetData(assetBinaryPath)
+            : {};
+      const sourceBasename = isRemoteSource(assetBinaryPath)
+        ? basename(new URL(assetBinaryPath).pathname)
+        : basename(assetBinaryPath);
+      const shortFilename = options.shortFilename || assetDataPartial.short_filename || sourceBasename;
+      const folderId = options.folder ? Number(options.folder) : undefined;
+      assetData = {
+        ...assetDataPartial,
+        short_filename: shortFilename,
+        asset_folder_id: folderId,
+      } satisfies AssetUpload;
+    }
 
-      /**
-       * Upsert Assets
-       */
-      const assetBinaryPath = typeof assetInput === 'string' && assetInput.trim().length > 0
-        ? assetInput
-        : undefined;
-      let assetData: AssetUpload | undefined;
-      if (assetBinaryPath) {
-        const assetDataPartial = options.data
-          ? parseAssetData(options.data)
-          : !isRemoteSource(assetBinaryPath)
-              ? await loadSidecarAssetData(assetBinaryPath)
-              : {};
-        const sourceBasename = isRemoteSource(assetBinaryPath)
-          ? basename(new URL(assetBinaryPath).pathname)
-          : basename(assetBinaryPath);
-        const shortFilename = options.shortFilename || assetDataPartial.short_filename || sourceBasename;
-        const folderId = options.folder ? Number(options.folder) : undefined;
-        assetData = {
-          ...assetDataPartial,
-          short_filename: shortFilename,
-          asset_folder_id: folderId,
-        } satisfies AssetUpload;
-      }
+    try {
+      for (const scope of scopes) {
+        const assetsDirectoryPath = resolveScopeBaseDir(scope, basePath);
+        const manifestFile = join(assetsDirectoryPath, 'manifest.jsonl');
+        const folderManifestFile = join(assetsDirectoryPath, 'folders', 'manifest.jsonl');
+        const transports = buildScopeTransports(scope, targetSpace);
 
-      const getAssetTransport = makeGetAssetAPITransport({ spaceId: targetSpace });
-      const createAssetTransport = options.dryRun
-        ? async (asset: AssetUpload) => asset as Asset
-        : makeCreateAssetAPITransport({ spaceId: targetSpace });
-      const updateAssetTransport = options.dryRun
-        ? async () => {}
-        : makeUpdateAssetAPITransport({ spaceId: targetSpace });
-      const assetManifestTransport = options.dryRun
-        ? () => Promise.resolve()
-        : makeAppendAssetManifestFSTransport({ manifestFile });
-      const cleanupAssetTransport = options.cleanup && !options.dryRun
-        ? makeCleanupAssetFSTransport()
-        : () => Promise.resolve();
+        const [assetMap, assetFolderMap] = await Promise.all([
+          loadAssetMap(manifestFile),
+          loadAssetFolderMap(folderManifestFile),
+        ]);
+        const maps = { assets: assetMap, assetFolders: assetFolderMap };
+        if (scope.kind === 'space') {
+          spaceAssetMap = maps.assets;
+          spaceManifestFile = manifestFile;
+        }
 
-      // Only build the target-space tag map for cross-space pushes; same-space
-      // pushes keep their IDs as-is. A failed fetch throws and aborts the push:
-      // fail fast rather than push unmappable IDs.
-      let assetInternalTagsByName = fromSpace === targetSpace
-        ? undefined
-        : await fetchAssetInternalTagsByName(targetSpace);
+        /**
+         * Upsert Asset Folders (skipped for single-asset pushes).
+         */
+        if (!assetBinaryPath) {
+          const assetFolderCreateTransport = options.dryRun
+            ? async (folder: AssetFolderCreate) => folder as AssetFolder
+            : transports.createAssetFolder;
+          const assetFolderUpdateTransport = options.dryRun
+            ? async (_id: number, folder: AssetFolderUpdate) => folder
+            : transports.updateAssetFolder;
+          const assetFolderManifestTransport = options.dryRun
+            ? () => Promise.resolve()
+            : makeAppendAssetFolderManifestFSTransport({ manifestFile: folderManifestFile });
+          const cleanupAssetFolderTransport = options.cleanup && !options.dryRun
+            ? makeCleanupAssetFolderFSTransport()
+            : () => Promise.resolve();
 
-      // Pre-create source tag names missing from the target space so pushed
-      // assets keep their tags instead of having the references dropped. Skipped
-      // on dry runs (no writes); creation is best-effort, a failed create leaves
-      // the name unmapped and the reference is dropped with the warning below.
-      if (assetInternalTagsByName && !options.dryRun) {
-        const sourceTagNames = assetBinaryPath
-          ? internalTagNamesFromAssets(assetData ? [assetData] : [])
-          : await collectAssetInternalTagNames(assetsDirectoryPath);
-        const createdTagLabels: string[] = [];
-        assetInternalTagsByName = await ensureAssetInternalTags({
-          sourceTagNames,
-          targetTagsByName: assetInternalTagsByName,
-          createTag: name => createAssetInternalTag(targetSpace, name),
-          onTagCreated: name => createdTagLabels.push(name),
-          onTagCreateError: (name, error) =>
-            logger.warn(`Failed to create internal asset tag "${name}"`, { error: error.message }),
-        });
-        if (createdTagLabels.length > 0) {
-          const labels = [...createdTagLabels].sort((a, b) => a.localeCompare(b));
-          const message = `Created ${labels.length} internal asset tag${labels.length === 1 ? '' : 's'} in target space: ${labels.join(', ')}`;
-          ui.info(message);
-          logger.info(message, { createdTags: labels });
+          summaries.push(...await upsertAssetFoldersPipeline({
+            directoryPath: join(assetsDirectoryPath, 'folders'),
+            logger,
+            maps,
+            transports: {
+              getAssetFolder: transports.getAssetFolder,
+              createAssetFolder: assetFolderCreateTransport,
+              updateAssetFolder: assetFolderUpdateTransport,
+              appendAssetFolderManifest: assetFolderManifestTransport,
+              cleanupAssetFolder: cleanupAssetFolderTransport,
+            },
+            ui,
+            // A library's root folder is a shared root folder that cannot be
+            // pushed from a space (org context only); skip it so the bulk push
+            // does not 403 on it while still pushing its child folders.
+            skipRootFolders: scope.kind === 'library',
+          }));
         }
-      }
 
-      const unmappedTagLabels = new Set<string>();
-      const onUnmappedTag = ({ sourceId, name }: UnmappedAssetInternalTag) => {
-        unmappedTagLabels.add(name ?? `#${sourceId}`);
-      };
+        /**
+         * Upsert Assets
+         */
+        // For library pushes, remap local tag IDs to the library's shared tags
+        // (creating missing ones) via the upsert stream's `resolveSharedTagIds`,
+        // which covers both the create and update paths. One resolver instance
+        // is shared so its fetched library-tag list is cached across the push.
+        const resolveSharedTagIds = scope.kind === 'library' && !options.dryRun
+          ? makeSharedTagResolver({ spaceId: targetSpace, libraryId: scope.libraryId })
+          : undefined;
+        // Default a missing asset folder to the library root before uploading:
+        // shared-asset creation requires an `asset_folder_id` the space can write
+        // to, so a missing one (single asset without --folder, or a sidecar that
+        // omits it) would 403.
+        const baseCreateAsset = scope.kind === 'library' && !options.dryRun
+          ? (() => {
+              const { libraryId } = scope;
+              return async (asset: AssetUpload, fileBuffer: ArrayBuffer) => {
+                const withFolder = asset.asset_folder_id == null
+                  ? { ...asset, asset_folder_id: libraryId }
+                  : asset;
+                return transports.createAsset(withFolder, fileBuffer);
+              };
+            })()
+          : transports.createAsset;
+        const createAssetTransport = options.dryRun
+          ? async (asset: AssetUpload) => asset as Asset
+          : baseCreateAsset;
+        const updateAssetTransport = options.dryRun
+          ? async () => {}
+          : transports.updateAsset;
+        const assetManifestTransport = options.dryRun
+          ? () => Promise.resolve()
+          : makeAppendAssetManifestFSTransport({ manifestFile });
+        const cleanupAssetTransport = options.cleanup && !options.dryRun
+          ? makeCleanupAssetFSTransport()
+          : () => Promise.resolve();
 
-      summaries.push(...await upsertAssetsPipeline({
-        assetBinaryPath,
-        assetData,
-        directoryPath: assetsDirectoryPath,
-        logger,
-        maps: { ...maps, assetInternalTagsByName },
-        transports: {
-          getAsset: getAssetTransport,
-          createAsset: createAssetTransport,
-          updateAsset: updateAssetTransport,
-          appendAssetManifest: assetManifestTransport,
-          cleanupAsset: cleanupAssetTransport,
-        },
-        ui,
-        onUnmappedTag,
-      }));
+        // Only build the target-space tag map for cross-space pushes; same-space
+        // pushes keep their IDs as-is. A failed fetch throws and aborts the push:
+        // fail fast rather than push unmappable IDs. Space scope only; libraries
+        // remap to their own shared tags.
+        let assetInternalTagsByName = scope.kind === 'space' && fromSpace !== targetSpace
+          ? await fetchAssetInternalTagsByName(targetSpace)
+          : undefined;
 
-      if (unmappedTagLabels.size > 0) {
-        const labels = [...unmappedTagLabels].sort((a, b) => a.localeCompare(b));
-        const message = `Dropped ${labels.length} unknown internal asset tag${labels.length === 1 ? '' : 's'} not present in target space: ${labels.join(', ')}`;
-        ui.warn(message);
-        logger.warn(message, { unmappedTags: labels });
-      }
+        // Pre-create source tag names missing from the target space so pushed
+        // assets keep their tags instead of having the references dropped. Skipped
+        // on dry runs (no writes); creation is best-effort, a failed create leaves
+        // the name unmapped and the reference is dropped with the warning below.
+        if (assetInternalTagsByName && !options.dryRun) {
+          const sourceTagNames = assetBinaryPath
+            ? internalTagNamesFromAssets(assetData ? [assetData] : [])
+            : await collectAssetInternalTagNames(assetsDirectoryPath);
+          const createdTagLabels: string[] = [];
+          assetInternalTagsByName = await ensureAssetInternalTags({
+            sourceTagNames,
+            targetTagsByName: assetInternalTagsByName,
+            createTag: name => createAssetInternalTag(targetSpace, name),
+            onTagCreated: name => createdTagLabels.push(name),
+            onTagCreateError: (name, error) =>
+              logger.warn(`Failed to create internal asset tag "${name}"`, { error: error.message }),
+          });
+          if (createdTagLabels.length > 0) {
+            const labels = [...createdTagLabels].sort((a, b) => a.localeCompare(b));
+            const message = `Created ${labels.length} internal asset tag${labels.length === 1 ? '' : 's'} in target space: ${labels.join(', ')}`;
+            ui.info(message);
+            logger.info(message, { createdTags: labels });
+          }
+        }
 
-      /**
-       * Map Asset References in Stories
-       */
-      const hasUpdatedFilename = (entry: { old: Asset | AssetMapped | AssetUpload; new: AssetMapped }) =>
-        'filename' in entry.old && entry.old.filename !== entry.new.filename;
-      const hasMetadata = (entry: { old: Asset | AssetMapped | AssetUpload; new: AssetMapped }) =>
-        'meta_data' in entry.new && entry.new.meta_data;
-      const hasUpdatedAssets = maps.assets.values().some(v => hasUpdatedFilename(v) || hasMetadata(v));
-      if (hasUpdatedAssets && options.updateStories) {
-        const schemas = await findComponentSchemas(resolveCommandPath(directories.components, fromSpace, basePath));
-        const writeStoryTransport = options.dryRun
-          ? async (story: Story) => story
-          : makeWriteStoryAPITransport({ spaceId: targetSpace });
+        const unmappedTagLabels = new Set<string>();
+        const onUnmappedTag = ({ sourceId, name }: UnmappedAssetInternalTag) => {
+          unmappedTagLabels.add(name ?? `#${sourceId}`);
+        };
 
-        summaries.push(...await mapAssetReferencesInStoriesPipeline({
+        summaries.push(...await upsertAssetsPipeline({
+          assetBinaryPath,
+          assetData,
+          directoryPath: assetsDirectoryPath,
           logger,
-          maps,
-          schemas,
-          space: targetSpace,
+          maps: { ...maps, assetInternalTagsByName, resolveSharedTagIds },
           transports: {
-            writeStory: writeStoryTransport,
+            getAsset: transports.getAsset,
+            createAsset: createAssetTransport,
+            updateAsset: updateAssetTransport,
+            appendAssetManifest: assetManifestTransport,
+            cleanupAsset: cleanupAssetTransport,
           },
           ui,
+          onUnmappedTag,
         }));
+
+        if (unmappedTagLabels.size > 0) {
+          const labels = [...unmappedTagLabels].sort((a, b) => a.localeCompare(b));
+          const message = `Dropped ${labels.length} unknown internal asset tag${labels.length === 1 ? '' : 's'} not present in target space: ${labels.join(', ')}`;
+          ui.warn(message);
+          logger.warn(message, { unmappedTags: labels });
+        }
+      }
+
+      /**
+       * Map Asset References in Stories (space scope only).
+       */
+      if (spaceAssetMap) {
+        const hasUpdatedFilename = (entry: { old: Asset | AssetMapped | AssetUpload; new: AssetMapped }) =>
+          'filename' in entry.old && entry.old.filename !== entry.new.filename;
+        const hasMetadata = (entry: { old: Asset | AssetMapped | AssetUpload; new: AssetMapped }) =>
+          'meta_data' in entry.new && entry.new.meta_data;
+        const hasUpdatedAssets = spaceAssetMap.values().some(v => hasUpdatedFilename(v) || hasMetadata(v));
+        if (hasUpdatedAssets && options.updateStories) {
+          const schemas = await findComponentSchemas(resolveCommandPath(directories.components, fromSpace, basePath));
+          const writeStoryTransport = options.dryRun
+            ? async (story: Story) => story
+            : makeWriteStoryAPITransport({ spaceId: targetSpace });
+
+          summaries.push(...await mapAssetReferencesInStoriesPipeline({
+            logger,
+            maps: { assets: spaceAssetMap },
+            schemas,
+            space: targetSpace,
+            transports: {
+              writeStory: writeStoryTransport,
+            },
+            ui,
+          }));
+        }
       }
 
-      if (!options.dryRun) {
-        await deduplicateManifest(manifestFile);
+      if (!options.dryRun && spaceManifestFile) {
+        await deduplicateManifest(spaceManifestFile);
       }
     }
     catch (maybeError) {
@@ -268,7 +417,9 @@ pushCmd
       }
       reporter.finalize();
 
-      const failedTotal = Object.values(summary).reduce((total, entry) => {
+      // Sum across the raw summaries array (not the deduped object): multiple
+      // scopes can emit the same summary key, and each scope's failures count.
+      const failedTotal = summaries.reduce((total, [, entry]) => {
         if (!entry || typeof entry.failed !== 'number') {
           return total;
         }
diff --git a/packages/cli/src/commands/assets/referenced.test.ts b/packages/cli/src/commands/assets/referenced.test.ts
new file mode 100644
index 000000000..bed630048
--- /dev/null
+++ b/packages/cli/src/commands/assets/referenced.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { collectReferencedAssetIds } from './referenced';
+
+describe('collectReferencedAssetIds', () => {
+  it('extracts numeric asset ids from story asset fields, including nested ones', () => {
+    const stories = [{
+      content: {
+        hero: { fieldtype: 'asset', id: 42, filename: 'x' },
+        body: [{ image: { fieldtype: 'asset', id: 43 } }],
+      },
+    }];
+
+    expect([...collectReferencedAssetIds(stories)].sort((a, b) => a - b)).toEqual([42, 43]);
+  });
+
+  it('ignores asset fields without a numeric id', () => {
+    const stories = [{ content: { hero: { fieldtype: 'asset', id: null, filename: '' } } }];
+
+    expect(collectReferencedAssetIds(stories).size).toBe(0);
+  });
+
+  it('returns an empty set when there are no stories', () => {
+    expect(collectReferencedAssetIds([]).size).toBe(0);
+  });
+});
diff --git a/packages/cli/src/commands/assets/referenced.ts b/packages/cli/src/commands/assets/referenced.ts
new file mode 100644
index 000000000..21605eec0
--- /dev/null
+++ b/packages/cli/src/commands/assets/referenced.ts
@@ -0,0 +1,87 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'pathe';
+
+interface AssetLike {
+  fieldtype?: string;
+  id?: number;
+}
+
+/**
+ * Recursively reads every `.json` story file under `directoryPath` and returns
+ * the parsed objects. Returns an empty array when the directory does not exist.
+ * Unparseable files are skipped.
+ */
+export async function readLocalStoryContents(directoryPath: string): Promise<{ content?: unknown }[]> {
+  const stories: { content?: unknown }[] = [];
+
+  const walk = async (dir: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch (maybeError) {
+      if ((maybeError as NodeJS.ErrnoException).code === 'ENOENT') {
+        return;
+      }
+      throw maybeError;
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      }
+      else if (entry.name.endsWith('.json')) {
+        try {
+          stories.push(JSON.parse(await readFile(full, 'utf-8')) as { content?: unknown });
+        }
+        catch {
+          // Skip files that are not valid story JSON.
+        }
+      }
+    }
+  };
+
+  await walk(directoryPath);
+  return stories;
+}
+
+/**
+ * Recursively walks story content and collects the numeric IDs of asset
+ * fields. Used by `assets pull --target=with-referenced` to discover which
+ * assets a space's stories reference, so referenced shared-library assets can
+ * be pulled alongside the space's own assets.
+ *
+ * Classification of those IDs into space-local vs. shared is done by the
+ * caller (id-based, never via URL prefix).
+ *
+ * Boundary: only nodes carrying `fieldtype: 'asset'` with a numeric `id` are
+ * collected (covers single- and multi-asset fields, including those nested in
+ * bloks). Rich-text-embedded assets — image nodes (`type: 'image'`,
+ * `attrs.id`) and asset links — do not use that shape and are NOT collected.
+ */
+export function collectReferencedAssetIds(stories: { content?: unknown }[]): Set<number> {
+  const ids = new Set<number>();
+
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (!node || typeof node !== 'object') {
+      return;
+    }
+    const obj = node as AssetLike & Record<string, unknown>;
+    if (obj.fieldtype === 'asset' && typeof obj.id === 'number') {
+      ids.add(obj.id);
+    }
+    for (const value of Object.values(obj)) {
+      visit(value);
+    }
+  };
+
+  for (const story of stories) {
+    visit(story.content);
+  }
+
+  return ids;
+}
diff --git a/packages/cli/src/commands/assets/scope.test.ts b/packages/cli/src/commands/assets/scope.test.ts
new file mode 100644
index 000000000..f8b646955
--- /dev/null
+++ b/packages/cli/src/commands/assets/scope.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { resolveScopeBaseDir, type Scope } from './scope';
+
+describe('resolveScopeBaseDir', () => {
+  it('returns the space subtree for a space scope', () => {
+    const scope: Scope = { kind: 'space', spaceId: '12345' };
+    expect(resolveScopeBaseDir(scope, undefined).replace(/\\/g, '/')).toContain('assets/12345');
+  });
+
+  it('returns a subtree for a non-numeric source directory (e.g. seed staging)', () => {
+    const scope: Scope = { kind: 'space', spaceId: 'qa-seed' };
+    expect(resolveScopeBaseDir(scope, undefined).replace(/\\/g, '/')).toContain('assets/qa-seed');
+  });
+
+  it('returns the shared/<libraryId> subtree for a library scope', () => {
+    const scope: Scope = { kind: 'library', libraryId: 7 };
+    expect(resolveScopeBaseDir(scope, undefined).replace(/\\/g, '/')).toContain('assets/shared/7');
+  });
+});
diff --git a/packages/cli/src/commands/assets/scope.ts b/packages/cli/src/commands/assets/scope.ts
new file mode 100644
index 000000000..fa8255a8a
--- /dev/null
+++ b/packages/cli/src/commands/assets/scope.ts
@@ -0,0 +1,107 @@
+import { join } from 'pathe';
+import { directories } from '../../constants';
+import { getMapiClient } from '../../api';
+import { handleAPIError } from '../../utils/error/api-error';
+import { toError } from '../../utils/error/error';
+import { resolveCommandPath } from '../../utils/filesystem';
+import type { SharedAssetFolder } from './types';
+
+/**
+ * Identifies the destination/source of an asset operation: the active space's
+ * own asset library, or one of the org's shared libraries.
+ */
+export type Scope =
+  // `spaceId` is the local source/destination directory segment (e.g. a space
+  // ID or a staging dir name like `qa-seed`), not necessarily a numeric ID.
+  | { kind: 'space'; spaceId: string }
+  | { kind: 'library'; libraryId: number };
+
+export interface Library {
+  id: number;
+  name: string;
+  uuid: string;
+  accessLevel: 'read' | 'write';
+}
+
+/**
+ * Resolves the on-disk base dir for a scope:
+ * `.storyblok/assets/<space_id>/` or `.storyblok/assets/shared/<library_id>/`.
+ */
+export function resolveScopeBaseDir(scope: Scope, basePath: string | undefined): string {
+  const segment = scope.kind === 'space'
+    ? String(scope.spaceId)
+    : join('shared', String(scope.libraryId));
+  return resolveCommandPath(directories.assets, segment, basePath);
+}
+
+/**
+ * Lists the top-level shared libraries the active space can access, with the
+ * space's own access level. A "library" is a shared asset folder with
+ * `parent_id === null`. Libraries the space cannot access are not returned.
+ */
+export async function listLibraries(spaceId: string): Promise<Library[]> {
+  try {
+    const { data } = await getMapiClient().sharedAssetFolders.list({
+      path: { space_id: Number(spaceId) },
+      throwOnError: true,
+    });
+    const folders: SharedAssetFolder[] = data?.shared_asset_folders ?? [];
+    return folders
+      .filter(folder => folder.parent_id === null || folder.parent_id === undefined)
+      .map(folder => ({
+        id: folder.id,
+        name: folder.name,
+        uuid: folder.uuid,
+        accessLevel: folder.asset_folder_access?.find(access => access.space_id === Number(spaceId))?.access_level ?? 'read',
+      }));
+  }
+  catch (maybeError) {
+    handleAPIError('pull_shared_asset_folders', toError(maybeError));
+  }
+}
+
+export const listReadableLibraries = (spaceId: string): Promise<Library[]> => listLibraries(spaceId);
+
+export const listWritableLibraries = async (spaceId: string): Promise<Library[]> =>
+  (await listLibraries(spaceId)).filter(library => library.accessLevel === 'write');
+
+/**
+ * Builds a resolver mapping any shared `asset_folder_id` to its top-level
+ * library root id (walking `parent_id` up). Fetches the space's shared folders
+ * once. Used to group referenced shared assets by library.
+ */
+export async function buildLibraryRootResolver(spaceId: string): Promise<(assetFolderId: number) => number> {
+  const { data } = await getMapiClient().sharedAssetFolders.list({
+    path: { space_id: Number(spaceId) },
+    throwOnError: true,
+  });
+  const parentById = new Map<number, number | null>();
+  for (const folder of data?.shared_asset_folders ?? []) {
+    parentById.set(folder.id, folder.parent_id ?? null);
+  }
+  return (assetFolderId: number): number => {
+    let current = assetFolderId;
+    const seen = new Set<number>();
+    while (!seen.has(current)) {
+      seen.add(current);
+      const parent = parentById.get(current);
+      if (parent === null || parent === undefined) {
+        return current;
+      }
+      current = parent;
+    }
+    return current;
+  };
+}
+
+/** Throws if the active space cannot write to the target library. */
+export async function assertLibraryWritable(spaceId: string, libraryId: number): Promise<Library> {
+  const library = (await listLibraries(spaceId)).find(candidate => candidate.id === libraryId);
+  if (!library) {
+    throw new Error(`Library ${libraryId} is not accessible from space ${spaceId}.`);
+  }
+  if (library.accessLevel !== 'write') {
+    throw new Error(`Library "${library.name}" (${libraryId}) is read-only for space ${spaceId}. No assets were pushed.`);
+  }
+  return library;
+}
diff --git a/packages/cli/src/commands/assets/streams.ts b/packages/cli/src/commands/assets/streams.ts
index 7babbd588..cf8485ed8 100644
--- a/packages/cli/src/commands/assets/streams.ts
+++ b/packages/cli/src/commands/assets/streams.ts
@@ -7,13 +7,13 @@ import { appendToFile, fileExists, saveToFile } from '../../utils/filesystem';
 import { toError } from '../../utils/error/error';
 import type { RegionCode } from '../../constants';
 import { SUPPORTED_ASSET_EXTENSIONS } from '../../constants';
-import { createAsset, createAssetFolder, downloadAssetFile, downloadFile, fetchAssetFolders, fetchAssets, updateAsset, updateAssetFolder } from './actions';
+import { createAsset, createAssetFolder, createSharedAsset, createSharedAssetFolder, createSharedInternalTag, downloadAssetFile, downloadFile, fetchAssetFolders, fetchAssets, fetchSharedAssetFolders, fetchSharedAssets, fetchSharedInternalTags, getSharedAsset, getSharedAssetFolder, updateAsset, updateAssetFolder, updateSharedAsset, updateSharedAssetFolder } from './actions';
 import type { Asset, AssetFolder, AssetFolderCreate, AssetFolderMap, AssetFolderUpdate, AssetInternalTagsByName, AssetListQuery, AssetMap, AssetUpdate, AssetUpload, UnmappedAssetInternalTag } from './types';
 import { getMapiClient } from '../../api';
 import { handleAPIError } from '../../utils/error/api-error';
 import { FetchError } from '../../utils/fetch';
 import { createPipelineBackpressureLock } from '../../utils/backpressure-lock';
-import { getAssetBinaryFilename, getAssetFilename, getFolderFilename, getSidecarFilename, isRemoteSource, loadSidecarAssetData } from './utils';
+import { extractAssetSizeFromFilename, getAssetBinaryFilename, getAssetFilename, getFolderFilename, getSidecarFilename, isRemoteSource, loadSidecarAssetData } from './utils';
 
 let _pipelineSlot: Sema | null = null;
 const getPipelineSlot = (): Sema => {
@@ -26,6 +26,7 @@ const getPipelineSlot = (): Sema => {
 export const fetchAssetsStream = ({
   spaceId,
   params = {},
+  fetchPage = fetchAssets,
   setTotalAssets,
   setTotalPages,
   onIncrement,
@@ -34,6 +35,8 @@ export const fetchAssetsStream = ({
 }: {
   spaceId: string;
   params?: AssetListQuery;
+  /** Page fetcher; defaults to the space `fetchAssets`. Shared libraries inject a `fetchSharedAssets` binding. */
+  fetchPage?: typeof fetchAssets;
   setTotalAssets?: (total: number) => void;
   setTotalPages?: (totalPages: number) => void;
   onIncrement?: () => void;
@@ -48,7 +51,7 @@ export const fetchAssetsStream = ({
 
     while (page <= totalPages) {
       try {
-        const result = await fetchAssets({
+        const result = await fetchPage({
           spaceId,
           params: {
             ...params,
@@ -84,6 +87,31 @@ export const fetchAssetsStream = ({
   return Readable.from(listGenerator());
 };
 
+/**
+ * Streams assets from a shared library via the `shared_assets` endpoints,
+ * filtered to `libraryId`. Reuses the space pagination loop by injecting a
+ * `fetchSharedAssets` page fetcher.
+ */
+export const fetchSharedAssetsStream = ({
+  spaceId,
+  libraryId,
+  ...rest
+}: {
+  spaceId: string;
+  libraryId: number;
+  params?: AssetListQuery;
+  setTotalAssets?: (total: number) => void;
+  setTotalPages?: (totalPages: number) => void;
+  onIncrement?: () => void;
+  onPageSuccess?: (page: number, total: number) => void;
+  onPageError?: (error: Error, page: number, total: number) => void;
+}) =>
+  fetchAssetsStream({
+    spaceId,
+    ...rest,
+    fetchPage: ({ params }) => fetchSharedAssets({ spaceId, libraryId, params }),
+  });
+
 export const downloadAssetStream = ({
   assetToken,
   region,
@@ -216,6 +244,41 @@ export const fetchAssetFoldersStream = ({
   return Readable.from(listGenerator());
 };
 
+/**
+ * Streams a library's shared folders (the library root and its descendants)
+ * via the `shared_asset_folders` endpoints.
+ */
+export const fetchSharedAssetFoldersStream = ({
+  spaceId,
+  libraryId,
+  setTotalFolders,
+  onSuccess,
+  onError,
+}: {
+  spaceId: string;
+  libraryId: number;
+  setTotalFolders?: (total: number) => void;
+  onSuccess?: (folders: AssetFolder[]) => void;
+  onError?: (error: Error) => void;
+}) => {
+  const listGenerator = async function* sharedFolderListIterator() {
+    try {
+      const { asset_folders } = await fetchSharedAssetFolders({ spaceId, libraryId });
+      setTotalFolders?.(asset_folders.length);
+      onSuccess?.(asset_folders);
+
+      for (const folder of asset_folders) {
+        yield folder;
+      }
+    }
+    catch (maybeError) {
+      onError?.(toError(maybeError));
+    }
+  };
+
+  return Readable.from(listGenerator());
+};
+
 export type WriteAssetFolderTransport = (folder: AssetFolder) => Promise<AssetFolder>;
 
 export const makeWriteAssetFolderFSTransport = ({ directoryPath }: {
@@ -273,6 +336,14 @@ export interface ReadLocalAssetFolderOptions {
   directoryPath: string;
   setTotalFolders?: (total: number) => void;
   onFolderError?: (error: Error) => void;
+  /**
+   * Skip root folders (`parent_id == null`). Shared libraries are themselves
+   * root shared folders that only exist in org context, so pushing one from a
+   * space 403s. Their children still resolve: a child's `parent_id` is the
+   * library's real id, which the upsert resolves without the root being pushed.
+   */
+  skipRootFolders?: boolean;
+  onFolderSkip?: () => void;
 }
 
 export interface LocalAssetFolderPayload {
@@ -286,6 +357,8 @@ export const readLocalAssetFoldersStream = ({
   directoryPath,
   setTotalFolders,
   onFolderError,
+  skipRootFolders,
+  onFolderSkip,
 }: ReadLocalAssetFolderOptions) => {
   const iterator = async function* readFolders() {
     try {
@@ -302,6 +375,13 @@ export const readLocalAssetFoldersStream = ({
             const content = await readFile(filePath, 'utf8');
             const folder = JSON.parse(content) as AssetFolder;
             jsonFiles.delete(file);
+            // Skip root folders when requested, but still mark them processed so
+            // their children resolve their parent and are not postponed forever.
+            if (skipRootFolders && !folder.parent_id) {
+              processed.add(folder.id);
+              onFolderSkip?.();
+              continue;
+            }
             // We must ensure the parent folder was already processed before
             // we can pass it to the next step in the pipeline. Otherwise,
             // mapping from local to remote parent ID does not work correctly.
@@ -650,9 +730,8 @@ export const makeCleanupAssetFSTransport = (): CleanupAssetTransport =>
 const hasId = (a: unknown): a is { id: number } => {
   return !!a && typeof a === 'object' && 'id' in a && typeof (a as any).id === 'number';
 };
-const hasShortFilename = (a: unknown): a is { short_filename: string } => {
-  return !!a && typeof a === 'object' && 'short_filename' in a && typeof (a as any).short_filename === 'string';
-};
+const hasProp = <K extends string>(a: unknown, key: K): a is Record<K, string> =>
+  !!a && typeof a === 'object' && key in a && typeof (a as any)[key] === 'string';
 
 const processAsset = async ({
   localAsset,
@@ -674,7 +753,7 @@ const processAsset = async ({
     appendAssetManifest: AppendAssetManifestTransport;
     cleanupAsset?: CleanupAssetTransport;
   };
-  maps: { assets: AssetMap; assetFolders: AssetFolderMap; assetInternalTagsByName?: AssetInternalTagsByName };
+  maps: { assets: AssetMap; assetFolders: AssetFolderMap; assetInternalTagsByName?: AssetInternalTagsByName; resolveSharedTagIds?: SharedTagResolver };
   onUnmappedTag?: (tag: UnmappedAssetInternalTag) => void;
 }): Promise<{ status: 'created' | 'updated'; remoteAsset: Asset }> => {
   const remoteFolderId = localAsset.asset_folder_id
@@ -685,16 +764,26 @@ const processAsset = async ({
   const remoteAsset = remoteAssetId ? await transports.getAsset(remoteAssetId) : null;
 
   const sourceTags = localAsset.internal_tags_list;
-  const resolveInternalTagIds = (sourceIds: ReadonlyArray<number | string> | undefined): string[] =>
-    maps.assetInternalTagsByName
+  // Library pushes resolve to the library's shared tags (creating missing ones);
+  // cross-space pushes map through the target space's tags by name; same-space
+  // pushes keep their IDs. Async because shared resolution may create tags.
+  const resolveInternalTagIds = async (sourceIds: ReadonlyArray<number | string> | undefined): Promise<string[]> => {
+    if (maps.resolveSharedTagIds) {
+      return maps.resolveSharedTagIds(sourceIds, sourceTags);
+    }
+    return maps.assetInternalTagsByName
       ? mapInternalTagIds(sourceIds, sourceTags, maps.assetInternalTagsByName, onUnmappedTag)
       : (sourceIds ?? []).map(id => String(id));
+  };
 
   let newRemoteAsset: Asset;
   let status: 'created' | 'updated';
   if (remoteAsset) {
     // Build only the writable metadata fields for the API update.
     // Read-only fields (filename, short_filename, etc.) are intentionally excluded.
+    const updateTagIds = 'internal_tag_ids' in localAsset
+      ? await resolveInternalTagIds(localAsset.internal_tag_ids)
+      : remoteAsset.internal_tag_ids;
     const updatePayload: AssetUpdate = {
       asset_folder_id: remoteFolderId,
       alt: 'alt' in localAsset ? localAsset.alt : remoteAsset.alt,
@@ -705,7 +794,7 @@ const processAsset = async ({
       focus: 'focus' in localAsset ? localAsset.focus : remoteAsset.focus,
       expire_at: 'expire_at' in localAsset ? localAsset.expire_at : remoteAsset.expire_at,
       publish_at: 'publish_at' in localAsset ? localAsset.publish_at : remoteAsset.publish_at,
-      internal_tag_ids: 'internal_tag_ids' in localAsset ? resolveInternalTagIds(localAsset.internal_tag_ids) : remoteAsset.internal_tag_ids,
+      internal_tag_ids: updateTagIds,
       meta_data: 'meta_data' in localAsset ? localAsset.meta_data : remoteAsset.meta_data,
     };
 
@@ -720,7 +809,7 @@ const processAsset = async ({
     newRemoteAsset = { ...remoteAsset, ...updatePayload };
     status = 'updated';
   }
-  else if (hasShortFilename(localAsset)) {
+  else if (hasProp(localAsset, 'short_filename')) {
     // `internal_tags_list` is server-managed (read-only) and must not be sent.
     // `internal_tag_ids` is rewritten through `maps.assetInternalTagsByName` so
     // source-space IDs are translated to target-space IDs. When the
@@ -728,12 +817,17 @@ const processAsset = async ({
     // the follow-up metadata PUT for tagless assets.
     const { internal_tags_list: _internalTagsList, internal_tag_ids: _sourceTagIds, ...rest } = localAsset;
     const mappedTagIds = 'internal_tag_ids' in localAsset
-      ? resolveInternalTagIds(localAsset.internal_tag_ids)
+      ? await resolveInternalTagIds(localAsset.internal_tag_ids)
       : undefined;
+    // Storyblok only keeps the `<width>x<height>` folder in the CDN URL when it
+    // was supplied at upload time; it is not derived server-side from the file.
+    // Carry it over from the source asset's filename so pushed assets keep it.
+    const size = hasProp(rest, 'size') ? rest.size : (hasProp(localAsset, 'filename') ? extractAssetSizeFromFilename(localAsset.filename) : undefined);
     const createPayload = {
       ...rest,
       asset_folder_id: remoteFolderId,
       ...(mappedTagIds !== undefined ? { internal_tag_ids: mappedTagIds } : {}),
+      ...(size !== undefined ? { size } : {}),
     } satisfies AssetUpload;
     newRemoteAsset = await transports.createAsset(createPayload, fileBuffer);
     status = 'created';
@@ -769,7 +863,7 @@ export const upsertAssetStream = ({
     appendAssetManifest: AppendAssetManifestTransport;
     cleanupAsset?: CleanupAssetTransport;
   };
-  maps: { assets: AssetMap; assetFolders: AssetFolderMap; assetInternalTagsByName?: AssetInternalTagsByName };
+  maps: { assets: AssetMap; assetFolders: AssetFolderMap; assetInternalTagsByName?: AssetInternalTagsByName; resolveSharedTagIds?: SharedTagResolver };
   onIncrement?: () => void;
   onAssetSuccess?: (localAsset: Asset | AssetUpload, remoteAsset: Asset) => void;
   onAssetError?: (error: Error, asset: Asset | AssetUpload) => void;
@@ -814,3 +908,102 @@ export const upsertAssetStream = ({
     },
   });
 };
+
+/**
+ * Shared (library) transport factories. These mirror their space-scoped
+ * counterparts above but bind to the `shared_*` API actions, so the existing
+ * upsert/write streams can drive a library scope unchanged.
+ */
+export const makeCreateSharedAssetAPITransport = ({ spaceId }: { spaceId: string }): CreateAssetTransport =>
+  (asset, fileBuffer) => createSharedAsset(asset, fileBuffer, { spaceId });
+
+export const makeUpdateSharedAssetAPITransport = ({ spaceId }: { spaceId: string }): UpdateAssetTransport =>
+  (id, asset, fileBuffer) => updateSharedAsset(id, asset, { spaceId, fileBuffer });
+
+export const makeGetSharedAssetAPITransport = ({ spaceId }: { spaceId: string }): GetAssetTransport =>
+  async (assetId: number) => {
+    const data = await getSharedAsset(assetId, { spaceId });
+    if (data?.deleted_at) {
+      return undefined;
+    }
+    return data;
+  };
+
+export const makeCreateSharedAssetFolderAPITransport = ({ spaceId }: { spaceId: string }): CreateAssetFolderTransport =>
+  folder => createSharedAssetFolder({
+    name: folder.name,
+    parent_id: folder.parent_id ?? undefined,
+  }, { spaceId });
+
+export const makeUpdateSharedAssetFolderAPITransport = ({ spaceId }: { spaceId: string }): UpdateAssetFolderTransport =>
+  // Whitelist mutable fields only. Pulled sidecars carry org-managed fields
+  // (`asset_folder_access`, `regions`, `uuid`, `id`); forwarding them on a
+  // space-context update 403s. Mirror the create transport.
+  (id, folder) => updateSharedAssetFolder(id, {
+    name: folder.name,
+    parent_id: folder.parent_id ?? undefined,
+  }, { spaceId });
+
+export const makeGetSharedAssetFolderAPITransport = ({ spaceId }: { spaceId: string }): GetAssetFolderTransport =>
+  folderId => getSharedAssetFolder(folderId, { spaceId });
+
+export type SharedTagResolver = (
+  sourceIds: ReadonlyArray<number | string> | undefined,
+  sourceTags: ReadonlyArray<{ id?: number; name?: string }> | null | undefined,
+) => Promise<string[]>;
+
+/**
+ * Builds a resolver that maps a local asset's `internal_tag_ids` to the
+ * matching shared (library-scoped) tag IDs for a library push, creating any
+ * missing tags in the library (`asset_folder_id` = library root). Uses the
+ * asset's `internal_tags_list` (`[{ id, name }]`) to map local IDs to names;
+ * IDs whose name is unknown are dropped. The library's tag list is fetched once
+ * and cached per push run. Mirrors `mapInternalTagIds` for the space scope so
+ * the shared create and update paths remap identically.
+ */
+export const makeSharedTagResolver = ({ spaceId, libraryId }: { spaceId: string; libraryId: number }): SharedTagResolver => {
+  let libraryTags: { id: number; name: string }[] | undefined;
+  const ensureTags = async () => {
+    if (!libraryTags) {
+      libraryTags = await fetchSharedInternalTags({ spaceId, libraryId });
+    }
+    return libraryTags;
+  };
+
+  return async (sourceIds, sourceTags) => {
+    if (!sourceIds || sourceIds.length === 0) {
+      return [];
+    }
+
+    const nameByLocalId = new Map<number, string>();
+    for (const tag of sourceTags ?? []) {
+      if (typeof tag?.id === 'number' && typeof tag.name === 'string') {
+        nameByLocalId.set(tag.id, tag.name);
+      }
+    }
+    const existing = await ensureTags();
+    const idByName = new Map(existing.map(tag => [tag.name, tag.id]));
+
+    const remapped: string[] = [];
+    for (const raw of sourceIds) {
+      const name = nameByLocalId.get(Number(raw));
+      if (!name) {
+        continue;
+      }
+      let sharedId = idByName.get(name);
+      if (sharedId === undefined) {
+        const created = await createSharedInternalTag({ name, object_type: 'asset', asset_folder_id: libraryId }, { spaceId });
+        if (created?.id) {
+          sharedId = created.id;
+          idByName.set(name, sharedId);
+          existing.push({ id: created.id, name });
+        }
+      }
+      if (sharedId !== undefined) {
+        remapped.push(String(sharedId));
+      }
+    }
+
+    return remapped;
+  };
+};
diff --git a/packages/cli/src/commands/assets/transfer/README.md b/packages/cli/src/commands/assets/transfer/README.md
index 20dc4c002..4d60a407b 100644
--- a/packages/cli/src/commands/assets/transfer/README.md
+++ b/packages/cli/src/commands/assets/transfer/README.md
@@ -1,6 +1,6 @@
 # Assets Transfer Command
 
-The `assets transfer` command transfers existing assets from a space's local library into the organization's global asset library. This is a one-way operation: assets move from a space to the organization. There is no reverse operation.
+The `assets transfer` command transfers existing assets from a space's local library into the organization's shared asset library. This is a one-way operation: assets move from a space to the organization. There is no reverse operation.
 
 ## Basic usage
 
@@ -27,7 +27,7 @@ storyblok assets transfer 123456 789012 --folder-id 789 --space YOUR_SPACE_ID --
 | Option | Description | Default |
 |--------|-------------|---------|
 | `<asset-id...>` | (Required) One or more numeric asset IDs to transfer | - |
-| `--folder-id <id>` | (Required) Destination folder ID in the global asset library | - |
+| `--folder-id <id>` | (Required) Destination folder ID in the shared asset library | - |
 | `-s, --space <id>` | Source space ID | Globally configured space |
 | `-d, --dry-run` | Print the transfer plan without making any API calls | `false` |
 
@@ -35,4 +35,4 @@ storyblok assets transfer 123456 789012 --folder-id 789 --space YOUR_SPACE_ID --
 
 - **Endpoint mapping:** The CLI exposes this operation as `transfer`, but it currently calls the backend `convert` endpoint (`POST /v1/spaces/{space_id}/assets/{id}/convert`), mapping `--folder-id` to the required `target_asset_folder_id` query parameter. This mapping will be removed once the backend ships the rename from `convert` to `transfer`.
 - **Plan required:** `--folder-id` is required and has no implicit default. Omitting it fails with an error.
-- **403 errors:** A 403 response comes from the backend authorization policy: the target folder must exist in the global asset library and the source space must have write access to it. Grant the space write access to the destination folder (or pick a folder it can write to), then retry.
+- **403 errors:** A 403 response comes from the backend authorization policy: the target folder must exist in the shared asset library and the source space must have write access to it. Grant the space write access to the destination folder (or pick a folder it can write to), then retry.
diff --git a/packages/cli/src/commands/assets/transfer/index.test.ts b/packages/cli/src/commands/assets/transfer/index.test.ts
index aed458147..58410eab2 100644
--- a/packages/cli/src/commands/assets/transfer/index.test.ts
+++ b/packages/cli/src/commands/assets/transfer/index.test.ts
@@ -54,7 +54,7 @@ describe('assets transfer command', () => {
   });
   afterAll(() => server.close());
 
-  it('should transfer a local asset to the global library', async () => {
+  it('should transfer a local asset to the shared library', async () => {
     preconditions.canTransferAssets();
 
     await assetsCommand.parseAsync(['node', 'test', 'transfer', '42', '--space', DEFAULT_SPACE, '--folder-id', '7']);
diff --git a/packages/cli/src/commands/assets/transfer/index.ts b/packages/cli/src/commands/assets/transfer/index.ts
index 6bd844136..347cc42fa 100644
--- a/packages/cli/src/commands/assets/transfer/index.ts
+++ b/packages/cli/src/commands/assets/transfer/index.ts
@@ -12,9 +12,9 @@ import { transferAssets } from '../actions';
 const transferCmd = assetsCommand
   .command('transfer <asset-id...>')
   .option('-s, --space <space>', 'space ID')
-  .option('--folder-id <folderId>', 'destination asset folder ID in the global library')
+  .option('--folder-id <folderId>', 'destination asset folder ID in the shared library')
   .option('-d, --dry-run', 'Preview changes without applying them to Storyblok')
-  .description(`Transfer space assets into the organization's global asset library.`);
+  .description(`Transfer space assets into the organization's shared asset library.`);
 
 transferCmd
   .action(async (assetIds: string[], options, command) => {
diff --git a/packages/cli/src/commands/assets/types.ts b/packages/cli/src/commands/assets/types.ts
index 801813195..3e296d1b7 100644
--- a/packages/cli/src/commands/assets/types.ts
+++ b/packages/cli/src/commands/assets/types.ts
@@ -1,6 +1,6 @@
-import type { Asset, AssetCreate, AssetFolder, AssetFolderCreate, AssetFolderUpdate, AssetListQuery, AssetUpdate } from '../../types';
+import type { Asset, AssetCreate, AssetFolder, AssetFolderCreate, AssetFolderUpdate, AssetListQuery, AssetUpdate, SharedAssetFolder, SharedAssetFolderCreate, SharedAssetFolderUpdate, SharedInternalTag, SharedInternalTagCreate } from '../../types';
 
-export type { Asset, AssetCreate, AssetFolder, AssetFolderCreate, AssetFolderUpdate, AssetListQuery, AssetUpdate };
+export type { Asset, AssetCreate, AssetFolder, AssetFolderCreate, AssetFolderUpdate, AssetListQuery, AssetUpdate, SharedAssetFolder, SharedAssetFolderCreate, SharedAssetFolderUpdate, SharedInternalTag, SharedInternalTagCreate };
 
 /**
  * CLI extension of mapi-client's AssetCreate.
diff --git a/packages/cli/src/commands/assets/utils.test.ts b/packages/cli/src/commands/assets/utils.test.ts
index b1d041ffc..c4790536a 100644
--- a/packages/cli/src/commands/assets/utils.test.ts
+++ b/packages/cli/src/commands/assets/utils.test.ts
@@ -1,6 +1,25 @@
 import { describe, expect, it, vi } from 'vitest';
 import { vol } from 'memfs';
-import { collectAssetInternalTagNames, ensureAssetInternalTags, internalTagNamesFromAssets } from './utils';
+import { collectAssetInternalTagNames, ensureAssetInternalTags, extractAssetSizeFromFilename, internalTagNamesFromAssets } from './utils';
+
+describe('extractAssetSizeFromFilename', () => {
+  it('extracts the dimensions segment from a CDN URL', () => {
+    expect(extractAssetSizeFromFilename('https://a.storyblok.com/f/329189/2048x1820/7fb286a4c5/image.jpg')).toBe('2048x1820');
+  });
+
+  it('returns undefined when the URL has no dimensions segment', () => {
+    expect(extractAssetSizeFromFilename('https://a.storyblok.com/f/293255674717942/8ae82d3a12/image.jpg')).toBeUndefined();
+  });
+
+  it('extracts the dimensions segment when it uses an uppercase X', () => {
+    expect(extractAssetSizeFromFilename('https://a.storyblok.com/f/329189/860X645/7aa24cb39f/image.jpg')).toBe('860X645');
+  });
+
+  it('returns undefined for an empty or invalid filename', () => {
+    expect(extractAssetSizeFromFilename(undefined)).toBeUndefined();
+    expect(extractAssetSizeFromFilename('not-a-url')).toBeUndefined();
+  });
+});
 
 describe('internalTagNamesFromAssets', () => {
   it('collects unique tag names in first-seen order, ignoring blanks', () => {
diff --git a/packages/cli/src/commands/assets/utils.ts b/packages/cli/src/commands/assets/utils.ts
index d27133148..fee6728e8 100644
--- a/packages/cli/src/commands/assets/utils.ts
+++ b/packages/cli/src/commands/assets/utils.ts
@@ -82,6 +82,25 @@ export const loadAssetFolderMap = async (manifestFile: string) => {
   return new Map(manifest.map(e => [Number(e.old_id), Number(e.new_id)])) satisfies AssetFolderMap;
 };
 
+/**
+ * Extracts the `<width>x<height>` dimensions segment from an asset CDN URL,
+ * e.g. `https://a.storyblok.com/f/123/2048x1820/hash/image.jpg` -> `2048x1820`.
+ * Storyblok only keeps this segment in the path when it was supplied at
+ * upload time (see `getAssetSizeForUpload`); it is not derived from the file.
+ */
+export const extractAssetSizeFromFilename = (filename?: string): string | undefined => {
+  if (!filename) {
+    return undefined;
+  }
+  try {
+    const segments = new URL(filename).pathname.split('/');
+    return segments.find(segment => /^\d+x\d+$/i.test(segment));
+  }
+  catch {
+    return undefined;
+  }
+};
+
 /**
  * Extracts the sanitized name and extension from an asset.
  * Uses short_filename if available, otherwise falls back to the filename basename.
diff --git a/packages/cli/src/commands/components/pull/README.md b/packages/cli/src/commands/components/pull/README.md
index e866d906f..5f6045d33 100644
--- a/packages/cli/src/commands/components/pull/README.md
+++ b/packages/cli/src/commands/components/pull/README.md
@@ -48,6 +48,9 @@ This will download a single component and its dependencies to:
 | `--sf, --separate-files` | Create a separate file for each component | `false` |
 | `--su, --suffix <suffix>` | Suffix to add to the files names  | |
 | `-p, --path <path>` | Custom path to store the files | `.storyblok/components` |
+| `--fi, --filter <glob>` | Glob pattern to select components by name | - |
+| `--gr, --group <name>` | Component group to select by name, or by a slash-separated path of nested group names (e.g. `Checkout/Payment`) to disambiguate. Repeatable, includes descendant groups | - |
+| `--tg, --tag <name>` | Component tag name to select. Repeatable and comma-separated | - |
 
 ## Examples
 
diff --git a/packages/cli/src/commands/components/pull/constants.ts b/packages/cli/src/commands/components/pull/constants.ts
index 6d52be5d7..5f29e9969 100644
--- a/packages/cli/src/commands/components/pull/constants.ts
+++ b/packages/cli/src/commands/components/pull/constants.ts
@@ -22,6 +22,20 @@ export interface PullComponentsOptions extends CommandOptions {
    * @default false
    */
   separateFiles?: boolean;
+  /**
+   * Glob pattern to select components by name. Matching components and their dependencies
+   * (assigned groups with ancestors, tags, presets, and schema-whitelisted groups/tags) are pulled.
+   */
+  filter?: string;
+  /**
+   * Component group name(s) or `Parent/Child` path(s) to select. Includes descendant groups.
+   * Repeatable; multiple values match any of the given groups.
+   */
+  group?: string[];
+  /**
+   * Component tag name(s) to select. Repeatable and comma-separated; multiple values match any.
+   */
+  tag?: string[];
 }
 
 export interface SaveComponentsOptions extends PullComponentsOptions {
@@ -32,7 +46,7 @@ export interface SaveComponentsOptions extends PullComponentsOptions {
    */
   path?: string;
   /**
-   * The regex filter to apply to the components before pushing.
+   * Glob pattern to select components by name before pushing.
    * @default `.*`
    */
   filter?: string;
diff --git a/packages/cli/src/commands/components/pull/index.test.ts b/packages/cli/src/commands/components/pull/index.test.ts
index afc4b58e3..36385c464 100644
--- a/packages/cli/src/commands/components/pull/index.test.ts
+++ b/packages/cli/src/commands/components/pull/index.test.ts
@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { session } from '../../../session';
 import { CommandError, konsola } from '../../../utils';
-import { fetchComponent, fetchComponents, saveComponentsToFiles } from './actions';
+import { fetchComponent, fetchComponentGroups, fetchComponentInternalTags, fetchComponents, saveComponentsToFiles } from './actions';
 import chalk from 'chalk';
 import { colorPalette } from '../../../constants';
 // Import the main module first to ensure proper initialization
@@ -271,4 +271,110 @@ describe('pull', () => {
       expect(ui.warn).toHaveBeenCalledWith(`The --filename option is ignored when using --separate-files`);
     });
   });
+
+  describe('--filter option', () => {
+    it('should save only components matching the glob and their dependencies', async () => {
+      const checkout = {
+        name: 'checkout-form',
+        display_name: 'Checkout Form',
+        id: 1,
+        created_at: '',
+        updated_at: '',
+        schema: { type: 'object' },
+        internal_tags_list: [] as { id?: number; name?: string }[],
+        internal_tag_ids: [] as string[],
+      };
+      const hero = {
+        name: 'hero',
+        display_name: 'Hero',
+        id: 2,
+        created_at: '',
+        updated_at: '',
+        schema: { type: 'object' },
+        internal_tags_list: [] as { id?: number; name?: string }[],
+        internal_tag_ids: [] as string[],
+      };
+
+      vi.mocked(fetchComponents).mockResolvedValue([checkout, hero]);
+
+      await componentsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--filter', 'checkout-*']);
+
+      expect(saveComponentsToFiles).toHaveBeenCalledWith('12345', expect.objectContaining({
+        components: [checkout],
+      }), expect.any(Object));
+    });
+
+    it('should warn and not save when the glob matches nothing', async () => {
+      const hero = {
+        name: 'hero',
+        display_name: 'Hero',
+        id: 2,
+        created_at: '',
+        updated_at: '',
+        schema: { type: 'object' },
+        internal_tags_list: [] as { id?: number; name?: string }[],
+        internal_tag_ids: [] as string[],
+      };
+      vi.mocked(fetchComponents).mockResolvedValue([hero]);
+
+      await componentsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--filter', 'checkout-*']);
+
+      expect(saveComponentsToFiles).not.toHaveBeenCalled();
+      expect(ui.warn).toHaveBeenCalledWith('No components found matching the given selectors.');
+    });
+  });
+
+  describe('--group and --tag options', () => {
+    const inCheckout = {
+      name: 'checkout-form',
+      display_name: 'Checkout Form',
+      id: 1,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      component_group_uuid: 'checkout',
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: ['10'],
+    };
+    const inMarketing = {
+      name: 'hero',
+      display_name: 'Hero',
+      id: 2,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      component_group_uuid: 'marketing',
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: [] as string[],
+    };
+    const checkoutGroup = { id: 1, uuid: 'checkout', name: 'Checkout' };
+    const marketingGroup = { id: 2, uuid: 'marketing', name: 'Marketing' };
+    const betaTag = { id: 10, name: 'beta' };
+
+    beforeEach(() => {
+      vi.mocked(fetchComponents).mockResolvedValue([inCheckout, inMarketing]);
+      vi.mocked(fetchComponentGroups).mockResolvedValue([checkoutGroup, marketingGroup]);
+      vi.mocked(fetchComponentInternalTags).mockResolvedValue([betaTag]);
+    });
+
+    it('pulls only components in the named group and its dependencies', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--group', 'Checkout']);
+      expect(saveComponentsToFiles).toHaveBeenCalledWith('12345', expect.objectContaining({
+        components: [inCheckout],
+      }), expect.any(Object));
+    });
+
+    it('pulls only components carrying the named tag', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--tag', 'beta']);
+      expect(saveComponentsToFiles).toHaveBeenCalledWith('12345', expect.objectContaining({
+        components: [inCheckout],
+      }), expect.any(Object));
+    });
+
+    it('errors on an unknown group name', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'pull', '--space', '12345', '--group', 'Ghost']);
+      expect(konsola.error).toHaveBeenCalledWith(expect.stringContaining('No component group found named "Ghost"'), null, { header: true });
+      expect(saveComponentsToFiles).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/packages/cli/src/commands/components/pull/index.ts b/packages/cli/src/commands/components/pull/index.ts
index ca2ec96f3..c87ffd9d2 100644
--- a/packages/cli/src/commands/components/pull/index.ts
+++ b/packages/cli/src/commands/components/pull/index.ts
@@ -12,6 +12,7 @@ import { resolveCommandPath } from '../../../utils/filesystem';
 import { DEFAULT_COMPONENTS_FILENAME } from '../constants';
 import { getUI } from '../../../utils/ui';
 import { getLogger } from '../../../lib/logger/logger';
+import { filterSpaceData, resolveGroupSelector, resolveTagSelector } from '../utils';
 
 const pullCmd = componentsCommand
   .command('pull [componentName]')
@@ -19,6 +20,9 @@ const pullCmd = componentsCommand
   .option('--sf, --separate-files', 'Argument to create a single file for each component')
   .option('--su, --suffix <suffix>', 'suffix to add to the file name (e.g. components.<suffix>.json)')
   .option('-s, --space <space>', 'space ID')
+  .option('--fi, --filter <filter>', 'glob pattern to select components by name')
+  .option('--gr, --group <group>', 'component group to select by name (e.g. "Checkout"), or by a slash-separated path of nested group names to disambiguate (e.g. "Checkout/Payment"). Repeatable, includes descendant groups', (value: string, previous: string[] = []) => [...previous, value])
+  .option('--tg, --tag <tag>', 'component tag name (repeatable, comma-separated)', (value: string, previous: string[] = []) => [...previous, ...value.split(',').map(v => v.trim()).filter(Boolean)])
   .description(`Download your space's components schema as json. Optionally specify a component name to pull a single component.`);
 
 pullCmd
@@ -33,6 +37,9 @@ pullCmd
       separateFiles = false,
       suffix,
       filename,
+      filter,
+      group,
+      tag,
     } = options;
 
     // Use default filename when not provided
@@ -59,15 +66,15 @@ pullCmd
 
     try {
       // Fetch components groups
-      const groups = await fetchComponentGroups(space);
+      let groups = await fetchComponentGroups(space);
       spinnerGroups.succeed(`${chalk.hex(colorPalette.COMPONENTS)('Groups')} - Completed in ${spinnerGroups.elapsedTime.toFixed(2)}ms`);
 
       // Fetch components presets
-      const presets = await fetchComponentPresets(space);
+      let presets = await fetchComponentPresets(space);
       spinnerPresets.succeed(`${chalk.hex(colorPalette.COMPONENTS)('Presets')} - Completed in ${spinnerPresets.elapsedTime.toFixed(2)}ms`);
 
       // Fetch components internal tags
-      const internalTags = await fetchComponentInternalTags(space);
+      let internalTags = await fetchComponentInternalTags(space);
       spinnerInternalTags.succeed(`${chalk.hex(colorPalette.COMPONENTS)('Tags')} - Completed in ${spinnerInternalTags.elapsedTime.toFixed(2)}ms`);
 
       // Save everything using the new structure
@@ -87,6 +94,30 @@ pullCmd
           spinnerComponents.failed(`No components found in the space ${space}`);
           return;
         }
+
+        const hasSelectors = Boolean(filter) || (group && group.length > 0) || (tag && tag.length > 0);
+        if (hasSelectors) {
+          const groupUuids = group && group.length > 0
+            ? new Set<string>(group.flatMap(g => [...resolveGroupSelector(groups || [], g)]))
+            : undefined;
+          const tagIds = tag && tag.length > 0
+            ? resolveTagSelector(internalTags || [], tag)
+            : undefined;
+
+          const filtered = filterSpaceData(
+            { components, groups: groups || [], presets: presets || [], internalTags: internalTags || [], datasources: [] },
+            { filter, groupUuids, tagIds },
+          );
+          if (filtered.components.length === 0) {
+            spinnerComponents.failed('No components found matching the given selectors.');
+            ui.warn('No components found matching the given selectors.');
+            return;
+          }
+          components = filtered.components;
+          groups = filtered.groups;
+          presets = filtered.presets;
+          internalTags = filtered.internalTags;
+        }
       }
       spinnerComponents.succeed(`${chalk.hex(colorPalette.COMPONENTS)('Components')} - Completed in ${spinnerComponents.elapsedTime.toFixed(2)}ms`);
       await saveComponentsToFiles(
diff --git a/packages/cli/src/commands/components/push/README.md b/packages/cli/src/commands/components/push/README.md
index 20bde4caf..620e12498 100644
--- a/packages/cli/src/commands/components/push/README.md
+++ b/packages/cli/src/commands/components/push/README.md
@@ -54,6 +54,8 @@ This will upload a single component and its dependencies from:
 | `-s, --space <space>`     | (Required) The ID of the space to push components to                                                           | -                       |
 | `-f, --from <from>`       | Source space ID to read components from                                                                        | Target space ID         |
 | `--fi, --filter <filter>` | Glob pattern to filter components by their name (e.g., "hero*" will match all components starting with "hero") | -                       |
+| `--gr, --group <name>`    | Component group to select by name, or by a slash-separated path of nested group names (e.g. `Checkout/Payment`) to disambiguate. Repeatable, includes descendant groups | -                       |
+| `--tg, --tag <name>`      | Component tag name to select. Repeatable and comma-separated                                                   | -                       |
 | `--sf, --separate-files`  | Read from separate files instead of consolidated files                                                         | `false`                 |
 | `--su, --suffix <suffix>` | Suffix to add to the files names                                                                               | -                       |
 | `-p, --path <path>`       | Custom path to read the files from                                                                             | `.storyblok/components` |
diff --git a/packages/cli/src/commands/components/push/constants.ts b/packages/cli/src/commands/components/push/constants.ts
index 08e8e26d9..cea45360c 100644
--- a/packages/cli/src/commands/components/push/constants.ts
+++ b/packages/cli/src/commands/components/push/constants.ts
@@ -22,6 +22,15 @@ export interface PushComponentsOptions extends CommandOptions {
    * Suffix to add to the component name.
    */
   suffix?: string;
+  /**
+   * Component group name(s) or `Parent/Child` path(s) to select from local files. Includes descendants.
+   * Repeatable; multiple values match any of the given groups.
+   */
+  group?: string[];
+  /**
+   * Component tag name(s) to select from local files. Repeatable and comma-separated; multiple values match any.
+   */
+  tag?: string[];
 }
 
 export interface ReadComponentsOptions extends PushComponentsOptions {
diff --git a/packages/cli/src/commands/components/push/index.test.ts b/packages/cli/src/commands/components/push/index.test.ts
index 77f950141..a2710d408 100644
--- a/packages/cli/src/commands/components/push/index.test.ts
+++ b/packages/cli/src/commands/components/push/index.test.ts
@@ -8,7 +8,7 @@ import '../index';
 import { componentsCommand } from '../command';
 import { loggedOutSessionState } from '../../../../test/setup';
 import { fetchComponentGroups, fetchComponentInternalTags, fetchComponentPresets, fetchComponents } from '../actions';
-import { deleteComponentPreset, upsertComponent } from './actions';
+import { deleteComponentPreset, upsertComponent, upsertComponentGroup } from './actions';
 import { getUI } from '../../../utils/ui';
 
 vi.mock('./actions', async () => {
@@ -257,4 +257,147 @@ describe('push', () => {
       expect(vi.mocked(deleteComponentPreset)).not.toHaveBeenCalled();
     });
   });
+
+  describe('--group option', () => {
+    const checkoutForm = {
+      name: 'checkout-form',
+      display_name: 'Checkout Form',
+      id: 1,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      component_group_uuid: 'checkout',
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: [] as string[],
+    };
+    const hero = {
+      name: 'hero',
+      display_name: 'Hero',
+      id: 2,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      component_group_uuid: 'marketing',
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: [] as string[],
+    };
+    const checkoutGroup = { id: 1, uuid: 'checkout', name: 'Checkout' };
+    const marketingGroup = { id: 2, uuid: 'marketing', name: 'Marketing' };
+
+    beforeEach(() => {
+      vol.fromJSON({
+        '.storyblok/components/source-space/components.json': JSON.stringify([checkoutForm, hero]),
+        '.storyblok/components/source-space/groups.json': JSON.stringify([checkoutGroup, marketingGroup]),
+      });
+      vi.mocked(fetchComponents).mockResolvedValue([]);
+      vi.mocked(fetchComponentGroups).mockResolvedValue([]);
+      vi.mocked(fetchComponentPresets).mockResolvedValue([]);
+      vi.mocked(fetchComponentInternalTags).mockResolvedValue([]);
+      vi.mocked(upsertComponent).mockResolvedValue(checkoutForm as unknown as Component);
+      vi.mocked(upsertComponentGroup).mockResolvedValue(checkoutGroup as any);
+    });
+
+    it('pushes only components in the named group', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'push', '--space', 'target-space', '--from', 'source-space', '--group', 'Checkout']);
+
+      const pushedNames = vi.mocked(upsertComponent).mock.calls.map(c => c[1]?.name);
+      expect(pushedNames).toContain('checkout-form');
+      expect(pushedNames).not.toContain('hero');
+    });
+
+    it('errors on an unknown group name', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'push', '--space', 'target-space', '--from', 'source-space', '--group', 'Ghost']);
+
+      expect(konsola.error).toHaveBeenCalledWith(expect.stringContaining('No component group found named "Ghost"'), null, { header: true });
+      expect(vi.mocked(upsertComponent)).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('--tag option', () => {
+    const taggedComponent = {
+      name: 'tagged',
+      display_name: 'Tagged',
+      id: 1,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: ['10'],
+    };
+    const untaggedComponent = {
+      name: 'untagged',
+      display_name: 'Untagged',
+      id: 2,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: [] as string[],
+    };
+    const betaTag = { id: 10, name: 'beta', object_type: 'component' };
+
+    beforeEach(() => {
+      vol.fromJSON({
+        '.storyblok/components/source-space/components.json': JSON.stringify([taggedComponent, untaggedComponent]),
+        '.storyblok/components/source-space/tags.json': JSON.stringify([betaTag]),
+      });
+      vi.mocked(fetchComponents).mockResolvedValue([]);
+      vi.mocked(fetchComponentGroups).mockResolvedValue([]);
+      vi.mocked(fetchComponentPresets).mockResolvedValue([]);
+      vi.mocked(fetchComponentInternalTags).mockResolvedValue([]);
+      vi.mocked(upsertComponent).mockResolvedValue(taggedComponent as unknown as Component);
+      vi.mocked(upsertComponentGroup).mockResolvedValue({} as any);
+    });
+
+    it('pushes only components carrying the named tag', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'push', '--space', 'target-space', '--from', 'source-space', '--tag', 'beta']);
+
+      const names = vi.mocked(upsertComponent).mock.calls.map(c => c[1]?.name);
+      expect(names).toContain('tagged');
+      expect(names).not.toContain('untagged');
+    });
+  });
+
+  describe('--filter option', () => {
+    const checkoutFormFilter = {
+      name: 'checkout-form',
+      display_name: 'Checkout Form',
+      id: 1,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: [] as string[],
+    };
+    const heroFilter = {
+      name: 'hero',
+      display_name: 'Hero',
+      id: 2,
+      created_at: '',
+      updated_at: '',
+      schema: { type: 'object' },
+      internal_tags_list: [] as { id?: number; name?: string }[],
+      internal_tag_ids: [] as string[],
+    };
+
+    beforeEach(() => {
+      vol.fromJSON({
+        '.storyblok/components/source-space/components.json': JSON.stringify([checkoutFormFilter, heroFilter]),
+      });
+      vi.mocked(fetchComponents).mockResolvedValue([]);
+      vi.mocked(fetchComponentGroups).mockResolvedValue([]);
+      vi.mocked(fetchComponentPresets).mockResolvedValue([]);
+      vi.mocked(fetchComponentInternalTags).mockResolvedValue([]);
+      vi.mocked(upsertComponent).mockResolvedValue(checkoutFormFilter as unknown as Component);
+      vi.mocked(upsertComponentGroup).mockResolvedValue({} as any);
+    });
+
+    it('pushes only components matching the glob filter', async () => {
+      await componentsCommand.parseAsync(['node', 'test', 'push', '--space', 'target-space', '--from', 'source-space', '--filter', 'checkout-*']);
+
+      const names = vi.mocked(upsertComponent).mock.calls.map(c => c[1]?.name);
+      expect(names).toContain('checkout-form');
+      expect(names).not.toContain('hero');
+    });
+  });
 });
diff --git a/packages/cli/src/commands/components/push/index.ts b/packages/cli/src/commands/components/push/index.ts
index 74b3c8c91..dd03930ca 100644
--- a/packages/cli/src/commands/components/push/index.ts
+++ b/packages/cli/src/commands/components/push/index.ts
@@ -6,7 +6,7 @@ import { CommandError, handleError, requireAuthentication } from '../../../utils
 import { session } from '../../../session';
 import { deleteComponentPreset, readComponentsFiles } from './actions';
 import { componentsCommand } from '../command';
-import { filterSpaceDataByComponent, filterSpaceDataByPattern } from './utils';
+import { filterSpaceData, filterSpaceDataByComponent, resolveGroupSelector, resolveTagSelector } from './utils';
 import { pushWithDependencyGraph } from './graph-operations';
 import chalk from 'chalk';
 import { getMapiClient } from '../../../api';
@@ -20,6 +20,8 @@ const pushCmd = componentsCommand
   .description(`Push your space's components schema as json`)
   .option('-f, --from <from>', 'source space id')
   .option('--fi, --filter <filter>', 'glob filter to apply to the components before pushing')
+  .option('--gr, --group <group>', 'component group to select by name (e.g. "Checkout"), or by a slash-separated path of nested group names to disambiguate (e.g. "Checkout/Payment"). Repeatable, includes descendant groups', (value: string, previous: string[] = []) => [...previous, value])
+  .option('--tg, --tag <tag>', 'component tag name (repeatable, comma-separated)', (value: string, previous: string[] = []) => [...previous, ...value.split(',').map(v => v.trim()).filter(Boolean)])
   .option('--sf, --separate-files', 'Read from separate files instead of consolidated files', false)
   .option('--su, --suffix <suffix>', 'Load only files matching *.<suffix>.json (e.g. components.dev.json)')
   .option('-s, --space <space>', 'space ID');
@@ -33,7 +35,7 @@ pushCmd
 
     const { space, path, verbose } = command.optsWithGlobals();
 
-    const { filter } = options;
+    const { filter, group, tag } = options;
     const fromSpace = options.from || space;
 
     // Check if the user is logged in
@@ -137,14 +139,22 @@ pushCmd
           return;
         }
       }
-      // If filter pattern is provided, filter space data to match the pattern
-      else if (filter) {
-        spaceState.local = filterSpaceDataByPattern(spaceState.local, filter);
+      // If a filter, group, or tag selector is provided, filter space data to match the selectors
+      else if (filter || (group && group.length > 0) || (tag && tag.length > 0)) {
+        const groupUuids = group && group.length > 0
+          ? new Set<string>(group.flatMap(g => [...resolveGroupSelector(spaceState.local.groups, g)]))
+          : undefined;
+        const tagIds = tag && tag.length > 0
+          ? resolveTagSelector(spaceState.local.internalTags, tag)
+          : undefined;
+
+        spaceState.local = filterSpaceData(spaceState.local, { filter, groupUuids, tagIds });
         if (!spaceState.local.components.length) {
-          handleError(new CommandError(`No components found matching pattern "${filter}".`), verbose);
+          handleError(new CommandError('No components found matching the given selectors.'), verbose);
           return;
         }
-        ui.info(`Filter applied: ${filter}`);
+        const applied = [filter && `filter ${filter}`, group?.length && `group ${group.join(', ')}`, tag?.length && `tag ${tag.join(', ')}`].filter(Boolean).join('; ');
+        ui.info(`Selectors applied: ${applied}`);
       }
 
       if (!spaceState.local.components.length) {
diff --git a/packages/cli/src/commands/components/push/utils.ts b/packages/cli/src/commands/components/push/utils.ts
index a1cfb2981..f32b97589 100644
--- a/packages/cli/src/commands/components/push/utils.ts
+++ b/packages/cli/src/commands/components/push/utils.ts
@@ -1,175 +1,2 @@
-import type { SpaceComponentsData } from '../constants';
-import { minimatch } from 'minimatch';
-import { collectWhitelistDependencies } from './graph-operations/dependency-graph';
-
-/**
- * Collects all dependencies (groups, tags, and components) for a set of components
- */
-function collectAllDependencies(
-  components: SpaceComponentsData['components'],
-  allComponents: SpaceComponentsData['components'],
-  allGroups: SpaceComponentsData['groups'],
-  allTags: SpaceComponentsData['internalTags'],
-) {
-  const requiredComponents = new Set<string>();
-  const requiredGroupUuids = new Set<string>();
-  const requiredTagIds = new Set<number>();
-
-  // Add initial components
-  components.forEach(component => requiredComponents.add(component.name));
-
-  // Recursively collect component dependencies
-  function collectComponentDeps(componentName: string, visited = new Set<string>()) {
-    if (visited.has(componentName)) { return; } // Prevent infinite loops
-    visited.add(componentName);
-
-    const component = allComponents.find(c => c.name === componentName);
-    if (!component) { return; }
-
-    // Collect direct component group assignment
-    if (component.component_group_uuid) {
-      requiredGroupUuids.add(component.component_group_uuid);
-    }
-
-    // Collect direct internal tag assignments
-    if (component.internal_tag_ids && component.internal_tag_ids.length > 0) {
-      component.internal_tag_ids.forEach((tagId) => {
-        // Handle both string and number tag IDs
-        const numericTagId = typeof tagId === 'string' ? Number.parseInt(tagId, 10) : tagId;
-        if (!Number.isNaN(numericTagId)) {
-          requiredTagIds.add(numericTagId);
-        }
-      });
-    }
-
-    // Collect schema whitelist dependencies
-    if (component.schema) {
-      const schemaDeps = collectWhitelistDependencies(component.schema);
-
-      // Add schema group dependencies
-      schemaDeps.groupUuids.forEach((groupUuid) => {
-        requiredGroupUuids.add(groupUuid);
-      });
-
-      // Add schema tag dependencies
-      schemaDeps.tagIds.forEach((tagId) => {
-        requiredTagIds.add(tagId);
-      });
-
-      // Add schema component dependencies (recursive)
-      schemaDeps.componentNames.forEach((componentName) => {
-        if (!requiredComponents.has(componentName)) {
-          requiredComponents.add(componentName);
-          collectComponentDeps(componentName, visited);
-        }
-      });
-    }
-  }
-
-  // Collect dependencies for all components
-  components.forEach(component => collectComponentDeps(component.name));
-
-  // Collect parent groups for hierarchical dependencies
-  function collectParentGroups(groupUuid: string, visited = new Set<string>()) {
-    if (visited.has(groupUuid)) { return; } // Prevent infinite loops
-    visited.add(groupUuid);
-
-    const group = allGroups.find(g => g.uuid === groupUuid);
-    if (group && group.parent_uuid) {
-      requiredGroupUuids.add(group.parent_uuid);
-      collectParentGroups(group.parent_uuid, visited);
-    }
-  }
-
-  // Ensure we include parent groups for all required groups
-  const initialGroupUuids = Array.from(requiredGroupUuids);
-  initialGroupUuids.forEach(groupUuid => collectParentGroups(groupUuid));
-
-  // Filter to only include required resources
-  const filteredComponents = allComponents.filter(component => requiredComponents.has(component.name));
-  const filteredGroups = allGroups.filter(group => group.uuid !== undefined && requiredGroupUuids.has(group.uuid));
-  const filteredTags = allTags.filter(tag => tag.id !== undefined && requiredTagIds.has(tag.id));
-
-  return { filteredComponents, filteredGroups, filteredTags };
-}
-
-/**
- * Filters space data to only include a specific component and its dependencies
- */
-export function filterSpaceDataByComponent(spaceData: SpaceComponentsData, componentName: string): SpaceComponentsData {
-  // Find the target component
-  const targetComponent = spaceData.components.find(component => component.name === componentName);
-  if (!targetComponent) {
-    return {
-      components: [],
-      groups: [],
-      internalTags: [],
-      presets: [],
-      datasources: [],
-    };
-  }
-
-  // Collect all dependencies for this component
-  const { filteredComponents, filteredGroups, filteredTags } = collectAllDependencies(
-    [targetComponent],
-    spaceData.components,
-    spaceData.groups,
-    spaceData.internalTags,
-  );
-
-  // Find presets for all included components
-  const componentIds = filteredComponents.map(component => component.id);
-  const filteredPresets = spaceData.presets.filter(
-    preset => componentIds.includes(preset.component_id),
-  );
-
-  return {
-    components: filteredComponents,
-    groups: filteredGroups,
-    internalTags: filteredTags,
-    presets: filteredPresets,
-    datasources: [],
-  };
-}
-
-/**
- * Filters space data to only include components matching a glob pattern and their dependencies
- */
-export function filterSpaceDataByPattern(spaceData: SpaceComponentsData, pattern: string): SpaceComponentsData {
-  // Filter components by pattern
-  const matchingComponents = spaceData.components.filter(component =>
-    minimatch(component.name, pattern),
-  );
-
-  if (matchingComponents.length === 0) {
-    return {
-      components: [],
-      groups: [],
-      internalTags: [],
-      presets: [],
-      datasources: [],
-    };
-  }
-
-  // Collect all dependencies for matching components
-  const { filteredComponents, filteredGroups, filteredTags } = collectAllDependencies(
-    matchingComponents,
-    spaceData.components,
-    spaceData.groups,
-    spaceData.internalTags,
-  );
-
-  // Find presets for all included components
-  const componentIds = filteredComponents.map(component => component.id);
-  const filteredPresets = spaceData.presets.filter(
-    preset => componentIds.includes(preset.component_id),
-  );
-
-  return {
-    components: filteredComponents,
-    groups: filteredGroups,
-    internalTags: filteredTags,
-    presets: filteredPresets,
-    datasources: [],
-  };
-}
+// Filter and dependency logic is shared with `pull` via the parent module.
+export { filterSpaceData, filterSpaceDataByComponent, resolveGroupSelector, resolveTagSelector } from '../utils';
diff --git a/packages/cli/src/commands/components/utils.test.ts b/packages/cli/src/commands/components/utils.test.ts
new file mode 100644
index 000000000..7fb03c48d
--- /dev/null
+++ b/packages/cli/src/commands/components/utils.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+import type { Component, ComponentFolder, InternalTag, SpaceComponentsData } from './constants';
+import { CommandError } from '../../utils';
+import { collectAllDependencies, filterSpaceData, resolveGroupSelector, resolveTagSelector } from './utils';
+
+function component(partial: Partial<Component> & { name: string }): Component {
+  return { id: 1, name: partial.name, schema: {}, ...partial } as Component;
+}
+
+function spaceData(components: Component[], extras: Partial<SpaceComponentsData> = {}): SpaceComponentsData {
+  return { components, groups: [], internalTags: [], presets: [], datasources: [], ...extras };
+}
+
+describe('collectAllDependencies (option A)', () => {
+  it('drops sibling components referenced via component_whitelist', () => {
+    const checkout = component({
+      name: 'checkout',
+      id: 1,
+      schema: { body: { type: 'bloks', component_whitelist: ['richtext'] } },
+    });
+    const richtext = component({ name: 'richtext', id: 2 });
+
+    const { filteredComponents } = collectAllDependencies(
+      [checkout],
+      [checkout, richtext],
+      [],
+      [],
+    );
+
+    expect(filteredComponents.map(c => c.name)).toEqual(['checkout']);
+  });
+
+  it('keeps the assigned group and its ancestors', () => {
+    const child: ComponentFolder = { id: 20, uuid: 'child-uuid', name: 'Child', parent_uuid: 'parent-uuid', parent_id: 10 };
+    const parent: ComponentFolder = { id: 10, uuid: 'parent-uuid', name: 'Parent' };
+    const checkout = component({ name: 'checkout', id: 1, component_group_uuid: 'child-uuid' });
+
+    const { filteredGroups } = collectAllDependencies([checkout], [checkout], [child, parent], []);
+
+    expect(filteredGroups.map(g => g.uuid).sort()).toEqual(['child-uuid', 'parent-uuid']);
+  });
+
+  it('keeps groups and tags referenced by schema whitelists, plus group ancestors', () => {
+    const parent: ComponentFolder = { id: 10, uuid: 'wl-parent', name: 'WLParent' };
+    const wlGroup: ComponentFolder = { id: 11, uuid: 'wl-group', name: 'WLGroup', parent_uuid: 'wl-parent', parent_id: 10 };
+    const tag: InternalTag = { id: 5, name: 'beta' };
+    const checkout = component({
+      name: 'checkout',
+      id: 1,
+      schema: {
+        body: {
+          type: 'bloks',
+          component_group_whitelist: ['wl-group'],
+          component_tag_whitelist: [5],
+        },
+      },
+    });
+
+    const { filteredGroups, filteredTags } = collectAllDependencies(
+      [checkout],
+      [checkout],
+      [wlGroup, parent],
+      [tag],
+    );
+
+    expect(filteredGroups.map(g => g.uuid).sort()).toEqual(['wl-group', 'wl-parent']);
+    expect(filteredTags.map(t => t.id)).toEqual([5]);
+  });
+
+  it('keeps directly assigned tags', () => {
+    const tag: InternalTag = { id: 7, name: 'checkout-team' };
+    const checkout = component({ name: 'checkout', id: 1, internal_tag_ids: ['7'] });
+
+    const { filteredTags } = collectAllDependencies([checkout], [checkout], [], [tag]);
+
+    expect(filteredTags.map(t => t.id)).toEqual([7]);
+  });
+});
+
+const groups: ComponentFolder[] = [
+  { id: 1, uuid: 'marketing', name: 'Marketing' },
+  { id: 2, uuid: 'checkout', name: 'Checkout', parent_uuid: 'marketing', parent_id: 1 },
+  { id: 3, uuid: 'checkout-forms', name: 'Forms', parent_uuid: 'checkout', parent_id: 2 },
+  { id: 4, uuid: 'blog', name: 'Blog' },
+  { id: 5, uuid: 'blog-forms', name: 'Forms', parent_uuid: 'blog', parent_id: 4 },
+];
+
+describe('resolveGroupSelector', () => {
+  it('resolves an unambiguous name to its subtree of uuids', () => {
+    expect([...resolveGroupSelector(groups, 'Checkout')].sort())
+      .toEqual(['checkout', 'checkout-forms']);
+  });
+
+  it('resolves a Parent/Child path', () => {
+    expect([...resolveGroupSelector(groups, 'Blog/Forms')]).toEqual(['blog-forms']);
+  });
+
+  it('includes descendants of the resolved group', () => {
+    expect([...resolveGroupSelector(groups, 'Marketing')].sort())
+      .toEqual(['checkout', 'checkout-forms', 'marketing']);
+  });
+
+  it('throws on an ambiguous bare name', () => {
+    expect(() => resolveGroupSelector(groups, 'Forms')).toThrow(/ambiguous/i);
+  });
+
+  it('throws when no group matches', () => {
+    expect(() => resolveGroupSelector(groups, 'Nope')).toThrow(/no component group/i);
+  });
+
+  it('throws on an ambiguous bare name without hanging when parent_uuid chain is cyclic', () => {
+    const cyclicGroups: ComponentFolder[] = [
+      { id: 1, uuid: 'a', name: 'Forms', parent_uuid: 'b' },
+      { id: 2, uuid: 'b', name: 'Forms', parent_uuid: 'a' },
+    ];
+    expect(() => resolveGroupSelector(cyclicGroups, 'Forms')).toThrow(CommandError);
+  });
+
+  it('throws when the selector produces no path segments', () => {
+    expect(() => resolveGroupSelector(groups, '/')).toThrow(CommandError);
+  });
+});
+
+describe('resolveTagSelector', () => {
+  const tags: InternalTag[] = [
+    { id: 10, name: 'beta' },
+    { id: 11, name: 'checkout-team' },
+  ];
+
+  it('maps names to ids', () => {
+    expect([...resolveTagSelector(tags, ['beta', 'checkout-team'])].sort((a, b) => a - b))
+      .toEqual([10, 11]);
+  });
+
+  it('throws when a tag name does not exist', () => {
+    expect(() => resolveTagSelector(tags, ['ghost'])).toThrow(/ghost/);
+  });
+});
+
+describe('filterSpaceData', () => {
+  const a = component({ name: 'checkout-form', id: 1, component_group_uuid: 'checkout', internal_tag_ids: ['10'] });
+  const b = component({ name: 'checkout-cart', id: 2, component_group_uuid: 'checkout', internal_tag_ids: [] });
+  const c = component({ name: 'hero', id: 3, component_group_uuid: 'marketing', internal_tag_ids: ['10'] });
+
+  it('combines selector types with AND', () => {
+    const result = filterSpaceData(spaceData([a, b, c]), {
+      groupUuids: new Set(['checkout']),
+      tagIds: new Set([10]),
+    });
+    expect(result.components.map(x => x.name)).toEqual(['checkout-form']);
+  });
+
+  it('matches tags with OR within the tag set', () => {
+    const result = filterSpaceData(spaceData([a, b, c]), { tagIds: new Set([10]) });
+    expect(result.components.map(x => x.name).sort()).toEqual(['checkout-form', 'hero']);
+  });
+
+  it('applies the glob on top of other selectors', () => {
+    const result = filterSpaceData(spaceData([a, b, c]), {
+      filter: 'checkout-*',
+      groupUuids: new Set(['checkout']),
+    });
+    expect(result.components.map(x => x.name).sort()).toEqual(['checkout-cart', 'checkout-form']);
+  });
+
+  it('returns empty data when nothing matches', () => {
+    const result = filterSpaceData(spaceData([a, b, c]), { groupUuids: new Set(['nope']) });
+    expect(result.components).toEqual([]);
+  });
+});
diff --git a/packages/cli/src/commands/components/utils.ts b/packages/cli/src/commands/components/utils.ts
new file mode 100644
index 000000000..b625f483c
--- /dev/null
+++ b/packages/cli/src/commands/components/utils.ts
@@ -0,0 +1,245 @@
+import type { Component, ComponentFolder, InternalTag, SpaceComponentsData } from './constants';
+import { minimatch } from 'minimatch';
+import { CommandError } from '../../utils';
+import { collectWhitelistDependencies } from './push/graph-operations/dependency-graph';
+
+/**
+ * Collects the dependencies required to make a set of matched components independently
+ * pushable: the matched components plus their assigned groups (with ancestors), assigned
+ * tags, and the groups/tags referenced by their own schema whitelists (groups with
+ * ancestors). Sibling components referenced via `component_whitelist` are NOT pulled in:
+ * those references are name-based, need no id remapping, and self-heal once a component of
+ * that name exists in the target. See adr/0005 for the full rationale.
+ */
+export function collectAllDependencies(
+  components: Component[],
+  allComponents: Component[],
+  allGroups: ComponentFolder[],
+  allTags: InternalTag[],
+) {
+  const requiredComponents = new Set<string>();
+  const requiredGroupUuids = new Set<string>();
+  const requiredTagIds = new Set<number>();
+
+  components.forEach(component => requiredComponents.add(component.name));
+
+  function collectComponentDeps(componentName: string, visited = new Set<string>()) {
+    if (visited.has(componentName)) { return; }
+    visited.add(componentName);
+
+    const component = allComponents.find(c => c.name === componentName);
+    if (!component) { return; }
+
+    if (component.component_group_uuid) {
+      requiredGroupUuids.add(component.component_group_uuid);
+    }
+
+    if (component.internal_tag_ids && component.internal_tag_ids.length > 0) {
+      component.internal_tag_ids.forEach((tagId) => {
+        const numericTagId = typeof tagId === 'string' ? Number.parseInt(tagId, 10) : tagId;
+        if (!Number.isNaN(numericTagId)) {
+          requiredTagIds.add(numericTagId);
+        }
+      });
+    }
+
+    if (component.schema) {
+      const schemaDeps = collectWhitelistDependencies(component.schema);
+      // Whitelisted groups/tags are referenced by id/uuid, which differ per space and can't
+      // self-heal, so they must travel with the component for the push to remap them.
+      schemaDeps.groupUuids.forEach(groupUuid => requiredGroupUuids.add(groupUuid));
+      schemaDeps.tagIds.forEach(tagId => requiredTagIds.add(tagId));
+      // Intentionally skip schemaDeps.componentNames: `component_whitelist` is name-based,
+      // needs no id remapping, and self-heals once a component of that name exists in the target.
+    }
+  }
+
+  components.forEach(component => collectComponentDeps(component.name));
+
+  function collectParentGroups(groupUuid: string, visited = new Set<string>()) {
+    if (visited.has(groupUuid)) { return; }
+    visited.add(groupUuid);
+
+    const group = allGroups.find(g => g.uuid === groupUuid);
+    if (group && group.parent_uuid) {
+      requiredGroupUuids.add(group.parent_uuid);
+      collectParentGroups(group.parent_uuid, visited);
+    }
+  }
+
+  const initialGroupUuids = Array.from(requiredGroupUuids);
+  initialGroupUuids.forEach(groupUuid => collectParentGroups(groupUuid));
+
+  const filteredComponents = allComponents.filter(component => requiredComponents.has(component.name));
+  const filteredGroups = allGroups.filter(group => group.uuid !== undefined && requiredGroupUuids.has(group.uuid));
+  const filteredTags = allTags.filter(tag => tag.id !== undefined && requiredTagIds.has(tag.id));
+
+  return { filteredComponents, filteredGroups, filteredTags };
+}
+
+function emptySpaceData(): SpaceComponentsData {
+  return { components: [], groups: [], internalTags: [], presets: [], datasources: [] };
+}
+
+/**
+ * Filters space data to only include a specific component (exact name) and its dependencies.
+ */
+export function filterSpaceDataByComponent(spaceData: SpaceComponentsData, componentName: string): SpaceComponentsData {
+  const targetComponent = spaceData.components.find(component => component.name === componentName);
+  if (!targetComponent) {
+    return emptySpaceData();
+  }
+
+  const { filteredComponents, filteredGroups, filteredTags } = collectAllDependencies(
+    [targetComponent],
+    spaceData.components,
+    spaceData.groups,
+    spaceData.internalTags,
+  );
+
+  const componentIds = filteredComponents.map(component => component.id);
+  const filteredPresets = spaceData.presets.filter(preset => componentIds.includes(preset.component_id));
+
+  return {
+    components: filteredComponents,
+    groups: filteredGroups,
+    internalTags: filteredTags,
+    presets: filteredPresets,
+    datasources: [],
+  };
+}
+
+export interface ComponentSelectors {
+  filter?: string;
+  groupUuids?: Set<string>;
+  tagIds?: Set<number>;
+}
+
+/**
+ * Filters space data by any combination of selectors. Selector types combine with AND;
+ * a glob matches component names, group membership matches the resolved subtree, tags match
+ * on intersection (OR within the tag set). Matched components are expanded to their
+ * dependencies via `collectAllDependencies`.
+ */
+export function filterSpaceData(spaceData: SpaceComponentsData, selectors: ComponentSelectors): SpaceComponentsData {
+  const { filter, groupUuids, tagIds } = selectors;
+
+  const base = spaceData.components.filter((component) => {
+    if (filter && !minimatch(component.name, filter)) { return false; }
+    if (groupUuids && !(component.component_group_uuid !== undefined && groupUuids.has(component.component_group_uuid))) { return false; }
+    if (tagIds) {
+      const ids = (component.internal_tag_ids ?? []).map(id => Number(id));
+      if (!ids.some(id => tagIds.has(id))) { return false; }
+    }
+    return true;
+  });
+
+  if (base.length === 0) {
+    return emptySpaceData();
+  }
+
+  const { filteredComponents, filteredGroups, filteredTags } = collectAllDependencies(
+    base,
+    spaceData.components,
+    spaceData.groups,
+    spaceData.internalTags,
+  );
+
+  const componentIds = filteredComponents.map(component => component.id);
+  const filteredPresets = spaceData.presets.filter(preset => componentIds.includes(preset.component_id));
+
+  return {
+    components: filteredComponents,
+    groups: filteredGroups,
+    internalTags: filteredTags,
+    presets: filteredPresets,
+    datasources: [],
+  };
+}
+
+/**
+ * Resolves a group selector (a name, or a `Parent/Child` path) to the set of UUIDs covering
+ * the matched group and all of its descendants. Throws when the name is ambiguous or missing.
+ */
+export function resolveGroupSelector(groups: ComponentFolder[], selector: string): Set<string> {
+  const byUuid = new Map(groups.filter(g => g.uuid).map(g => [g.uuid as string, g]));
+  const nameOf = (uuid?: string) => (uuid ? byUuid.get(uuid)?.name : undefined);
+
+  let matched: ComponentFolder | undefined;
+
+  if (selector.includes('/')) {
+    const segments = selector.split('/').map(s => s.trim()).filter(Boolean);
+    if (segments.length === 0) {
+      throw new CommandError(`No component group found for path "${selector}".`);
+    }
+    let parentUuid: string | undefined;
+    for (const segment of segments) {
+      const candidates = groups.filter(g => g.name === segment && (g.parent_uuid ?? undefined) === parentUuid);
+      if (candidates.length === 0) {
+        throw new CommandError(`No component group found for path "${selector}".`);
+      }
+      if (candidates.length > 1) {
+        throw new CommandError(`The component group path "${selector}" is ambiguous.`);
+      }
+      matched = candidates[0];
+      parentUuid = matched.uuid;
+    }
+  }
+  else {
+    const candidates = groups.filter(g => g.name === selector);
+    if (candidates.length === 0) {
+      throw new CommandError(`No component group found named "${selector}".`);
+    }
+    if (candidates.length > 1) {
+      const paths = candidates.map((g) => {
+        const parts = [g.name];
+        const visited = new Set<string>();
+        let p = g.parent_uuid;
+        while (p && !visited.has(p)) {
+          visited.add(p);
+          parts.unshift(nameOf(p) ?? p);
+          p = byUuid.get(p)?.parent_uuid;
+        }
+        return parts.join('/');
+      });
+      throw new CommandError(`The component group name "${selector}" is ambiguous. Use a path: ${paths.join(', ')}.`);
+    }
+    matched = candidates[0];
+  }
+
+  const result = new Set<string>();
+  const queue: string[] = matched?.uuid ? [matched.uuid] : [];
+  while (queue.length > 0) {
+    const uuid = queue.shift() as string;
+    if (result.has(uuid)) { continue; }
+    result.add(uuid);
+    for (const child of groups) {
+      if (child.parent_uuid === uuid && child.uuid) {
+        queue.push(child.uuid);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Resolves tag names to their numeric ids. Throws when any name is missing.
+ */
+export function resolveTagSelector(tags: InternalTag[], names: string[]): Set<number> {
+  const byName = new Map(tags.filter(t => t.id !== undefined).map(t => [t.name, t.id as number]));
+  const result = new Set<number>();
+  const missing: string[] = [];
+  for (const name of names) {
+    const id = byName.get(name);
+    if (id === undefined) {
+      missing.push(name);
+    }
+    else {
+      result.add(id);
+    }
+  }
+  if (missing.length > 0) {
+    throw new CommandError(`No component tag found named: ${missing.join(', ')}.`);
+  }
+  return result;
+}
diff --git a/packages/cli/src/commands/create/actions.test.ts b/packages/cli/src/commands/create/actions.test.ts
index 4cde18384..6d879ccab 100644
--- a/packages/cli/src/commands/create/actions.test.ts
+++ b/packages/cli/src/commands/create/actions.test.ts
@@ -1,21 +1,13 @@
 import { spawn } from 'node:child_process';
-import fs from 'node:fs/promises';
 import { vol } from 'memfs';
 import { beforeEach, describe, expect, it, type MockedFunction, vi } from 'vitest';
 import open from 'open';
-import { createEnvFile, extractPortFromTopics, fetchBlueprintRepositories, generateProject, handleEnvFileCreation, openSpaceInBrowser, repositoryToTemplate } from './actions';
-import * as filesystem from '../../utils/filesystem';
+import { createEnvFile, extractPortFromTopics, fetchBlueprintRepositories, generateProject, handleEnvFileCreation, openSpaceInBrowser, repositoryToTemplate, updateAngularEnvironmentFiles } from './actions';
 import type { RegionCode } from '../../constants';
 import { appDomains } from '../../constants';
 
 vi.mock('node:child_process');
-vi.mock('node:fs/promises', () => ({
-  default: {
-    access: vi.fn(),
-  },
-}));
 vi.mock('open');
-vi.mock('../../utils/filesystem');
 vi.mock('../../github', () => ({
   createOctokit: vi.fn(),
 }));
@@ -33,8 +25,6 @@ vi.mock('../../utils/ui', () => ({
 
 const mockedSpawn = vi.mocked(spawn);
 const mockedOpen = open as MockedFunction<typeof open>;
-const mockedSaveToFile = filesystem.saveToFile as MockedFunction<typeof filesystem.saveToFile>;
-const mockedFsAccess = vi.mocked(fs.access);
 
 // Import the mocked modules
 const { createOctokit } = await import('../../github');
@@ -48,10 +38,7 @@ describe('create actions', () => {
 
   describe('generateProject', () => {
     it('should generate project successfully when directory does not exist', async () => {
-      const accessError = new Error('ENOENT: no such file or directory') as NodeJS.ErrnoException;
-      accessError.code = 'ENOENT';
-      mockedFsAccess.mockRejectedValueOnce(accessError);
-
+      // Directory does not exist - vol is empty
       const mockProcess = {
         on: vi.fn((event: string, callback: (code: number) => void) => {
           if (event === 'close') {
@@ -63,7 +50,6 @@ describe('create actions', () => {
 
       await expect(generateProject('react', 'my-project', '/test/path')).resolves.toBeUndefined();
 
-      expect(mockedFsAccess).toHaveBeenCalledWith('/test/path/my-project');
       expect(mockedSpawn).toHaveBeenCalledWith(
         'npx',
         ['degit', 'storyblok/blueprint-core-react', '/test/path/my-project'],
@@ -75,37 +61,22 @@ describe('create actions', () => {
     });
 
     it('should throw FileSystemError when directory already exists', async () => {
-      mockedFsAccess.mockResolvedValueOnce(undefined);
+      // Create existing directory in memfs
+      vol.fromJSON({
+        '/test/path/existing-project/.gitkeep': '',
+      });
 
-      await expect(generateProject('vue', 'existing-project')).rejects.toThrow(
+      await expect(generateProject('vue', 'existing-project', '/test/path')).rejects.toThrow(
         expect.objectContaining({
           name: 'File System Error',
           errorId: 'directory_not_empty',
           code: 'ENOTEMPTY',
         }),
       );
-
-      expect(mockedFsAccess).toHaveBeenCalledWith(expect.stringContaining('existing-project'));
-    });
-
-    it('should handle filesystem errors other than ENOENT', async () => {
-      const accessError = new Error('EACCES: permission denied') as NodeJS.ErrnoException;
-      accessError.code = 'EACCES';
-      mockedFsAccess.mockRejectedValueOnce(accessError);
-
-      await expect(generateProject('svelte', 'test-project')).rejects.toThrow(
-        expect.objectContaining({
-          name: 'File System Error',
-          errorId: 'permission_denied',
-        }),
-      );
     });
 
     it('should handle spawn process failure', async () => {
-      const accessError = new Error('ENOENT: no such file or directory') as NodeJS.ErrnoException;
-      accessError.code = 'ENOENT';
-      mockedFsAccess.mockRejectedValueOnce(accessError);
-
+      // Directory does not exist - vol is empty
       const mockProcess = {
         on: vi.fn((event: string, callback: (code: number) => void) => {
           if (event === 'close') {
@@ -115,16 +86,13 @@ describe('create actions', () => {
       };
       mockedSpawn.mockReturnValue(mockProcess as any);
 
-      await expect(generateProject('react', 'failed-project')).rejects.toThrow(
+      await expect(generateProject('react', 'failed-project', '/test/path')).rejects.toThrow(
         'Failed to clone template. Process exited with code 1',
       );
     });
 
     it('should handle spawn process error', async () => {
-      const accessError = new Error('ENOENT: no such file or directory') as NodeJS.ErrnoException;
-      accessError.code = 'ENOENT';
-      mockedFsAccess.mockRejectedValueOnce(accessError);
-
+      // Directory does not exist - vol is empty
       const mockProcess = {
         on: vi.fn((event: string, callback: (error: Error) => void) => {
           if (event === 'error') {
@@ -134,16 +102,13 @@ describe('create actions', () => {
       };
       mockedSpawn.mockReturnValue(mockProcess as any);
 
-      await expect(generateProject('react', 'error-project')).rejects.toThrow(
+      await expect(generateProject('react', 'error-project', '/test/path')).rejects.toThrow(
         'Failed to spawn degit process: spawn failed',
       );
     });
 
     it('should use current working directory as default target path', async () => {
-      const accessError = new Error('ENOENT: no such file or directory') as NodeJS.ErrnoException;
-      accessError.code = 'ENOENT';
-      mockedFsAccess.mockRejectedValueOnce(accessError);
-
+      // Directory does not exist - vol is empty
       const mockProcess = {
         on: vi.fn((event: string, callback: (code: number) => void) => {
           if (event === 'close') {
@@ -157,7 +122,14 @@ describe('create actions', () => {
 
       await generateProject('react', 'my-project');
 
-      expect(mockedFsAccess).toHaveBeenCalledWith('/current/dir/my-project');
+      expect(mockedSpawn).toHaveBeenCalledWith(
+        'npx',
+        ['degit', 'storyblok/blueprint-core-react', '/current/dir/my-project'],
+        {
+          stdio: 'inherit',
+          shell: true,
+        },
+      );
 
       vi.mocked(process.cwd).mockRestore();
     });
@@ -165,18 +137,20 @@ describe('create actions', () => {
 
   describe('createEnvFile', () => {
     it('should create .env file successfully with access token only', async () => {
-      mockedSaveToFile.mockResolvedValue(undefined);
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
 
       await createEnvFile('/test/project', { STORYBLOK_DELIVERY_API_TOKEN: 'test-token-123' });
 
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringContaining('STORYBLOK_DELIVERY_API_TOKEN=test-token-123'),
-      );
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
+      expect(content).toContain('STORYBLOK_DELIVERY_API_TOKEN=test-token-123');
     });
 
     it('should create .env file with additional variables', async () => {
-      mockedSaveToFile.mockResolvedValue(undefined);
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
 
       const additionalVars = {
         CUSTOM_VAR: 'custom-value',
@@ -185,36 +159,20 @@ describe('create actions', () => {
 
       await createEnvFile('/test/project', { STORYBLOK_DELIVERY_API_TOKEN: 'test-token-123' }, additionalVars);
 
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringMatching(/STORYBLOK_DELIVERY_API_TOKEN=test-token-123/),
-      );
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringMatching(/CUSTOM_VAR=custom-value/),
-      );
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringMatching(/ANOTHER_VAR=another-value/),
-      );
-    });
-
-    it('should handle filesystem errors when creating .env file', async () => {
-      const saveError = new Error('Permission denied');
-      mockedSaveToFile.mockRejectedValue(saveError);
-
-      await expect(createEnvFile('/test/project', { STORYBLOK_DELIVERY_API_TOKEN: 'test-token-123' })).rejects.toThrow(
-        'Failed to create .env file: Permission denied',
-      );
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
+      expect(content).toMatch(/STORYBLOK_DELIVERY_API_TOKEN=test-token-123/);
+      expect(content).toMatch(/CUSTOM_VAR=custom-value/);
+      expect(content).toMatch(/ANOTHER_VAR=another-value/);
     });
 
     it('should create proper .env file content structure', async () => {
-      mockedSaveToFile.mockResolvedValue(undefined);
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
 
       await createEnvFile('/test/project', { STORYBLOK_DELIVERY_API_TOKEN: 'test-token-123' }, { CUSTOM: 'value' });
 
-      const [[, content]] = mockedSaveToFile.mock.calls;
-
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
       expect(content).toMatch(/^# Storyblok Configuration/);
       expect(content).toMatch(/STORYBLOK_DELIVERY_API_TOKEN=test-token-123/);
       expect(content).toMatch(/# Additional Configuration/);
@@ -224,32 +182,29 @@ describe('create actions', () => {
 
   describe('handleEnvFileCreation', () => {
     it('should create .env file with token and region successfully', async () => {
-      mockedSaveToFile.mockResolvedValue(undefined);
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
 
       const result = await handleEnvFileCreation('/test/project', 'test-token-123', 'us');
 
       expect(result).toBe(true);
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringContaining('STORYBLOK_DELIVERY_API_TOKEN=test-token-123'),
-      );
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringContaining('STORYBLOK_REGION=us'),
-      );
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
+      expect(content).toContain('STORYBLOK_DELIVERY_API_TOKEN=test-token-123');
+      expect(content).toContain('STORYBLOK_REGION=us');
       expect(mockedUI.ok).toHaveBeenCalledWith(expect.stringContaining('Created .env file with'), true);
     });
 
     it('should create .env file with only token', async () => {
-      mockedSaveToFile.mockResolvedValue(undefined);
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
 
       const result = await handleEnvFileCreation('/test/project', 'test-token-456');
 
       expect(result).toBe(true);
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringContaining('STORYBLOK_DELIVERY_API_TOKEN=test-token-456'),
-      );
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
+      expect(content).toContain('STORYBLOK_DELIVERY_API_TOKEN=test-token-456');
       expect(mockedUI.ok).toHaveBeenCalledWith(
         expect.stringContaining('Created .env file with'),
         true,
@@ -257,15 +212,15 @@ describe('create actions', () => {
     });
 
     it('should create .env file with only region', async () => {
-      mockedSaveToFile.mockResolvedValue(undefined);
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
 
       const result = await handleEnvFileCreation('/test/project', undefined, 'ap');
 
       expect(result).toBe(true);
-      expect(mockedSaveToFile).toHaveBeenCalledWith(
-        '/test/project/.env',
-        expect.stringContaining('STORYBLOK_REGION=ap'),
-      );
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
+      expect(content).toContain('STORYBLOK_REGION=ap');
       expect(mockedUI.ok).toHaveBeenCalledWith(expect.stringContaining('Created .env file with'), true);
     });
 
@@ -274,62 +229,139 @@ describe('create actions', () => {
 
       expect(result).toBe(true);
       expect(mockedUI.info).toHaveBeenCalledWith('No environment variables to write');
-      expect(mockedSaveToFile).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('updateAngularEnvironmentFiles', () => {
+    const angularEnvTemplate = `export const environment = {
+  production: true,
+  accessToken: 'STORYBLOK_DELIVERY_API_TOKEN', // Replace with your Storyblok Delivery API token
+  region: 'STORYBLOK_REGION', // Replace with your Storyblok region
+};`;
+
+    it('should replace both token and region placeholders', async () => {
+      vol.fromJSON({
+        '/test/project/src/environments/environment.ts': angularEnvTemplate,
+        '/test/project/src/environments/environment.development.ts': angularEnvTemplate,
+      });
+
+      const result = await updateAngularEnvironmentFiles('/test/project', 'my-actual-token', 'eu');
+
+      expect(result.updatedFiles).toEqual([
+        '/test/project/src/environments/environment.ts',
+        '/test/project/src/environments/environment.development.ts',
+      ]);
+
+      const envContent = vol.readFileSync('/test/project/src/environments/environment.ts', 'utf-8');
+      expect(envContent).toContain('accessToken: \'my-actual-token\'');
+      expect(envContent).toContain('region: \'eu\'');
+
+      const devEnvContent = vol.readFileSync('/test/project/src/environments/environment.development.ts', 'utf-8');
+      expect(devEnvContent).toContain('accessToken: \'my-actual-token\'');
+      expect(devEnvContent).toContain('region: \'eu\'');
     });
 
-    it('should handle errors gracefully and return false', async () => {
-      const saveError = new Error('Permission denied');
-      mockedSaveToFile.mockRejectedValue(saveError);
+    it('should replace only token placeholder when region not provided', async () => {
+      vol.fromJSON({
+        '/test/project/src/environments/environment.ts': angularEnvTemplate,
+        '/test/project/src/environments/environment.development.ts': angularEnvTemplate,
+      });
 
-      const result = await handleEnvFileCreation('/test/project', 'test-token-789', 'eu');
+      await updateAngularEnvironmentFiles('/test/project', 'my-token');
 
-      expect(result).toBe(false);
-      expect(mockedUI.warn).toHaveBeenCalledWith(
-        expect.stringContaining('Failed to create .env file: Permission denied'),
-      );
-      expect(mockedUI.info).toHaveBeenCalledWith(
-        expect.stringContaining('You can manually add STORYBLOK_DELIVERY_API_TOKEN'),
-      );
-      expect(mockedUI.info).toHaveBeenCalledWith(
-        expect.stringContaining('You can manually add STORYBLOK_REGION'),
-      );
+      const content = vol.readFileSync('/test/project/src/environments/environment.ts', 'utf-8');
+      expect(content).toContain('accessToken: \'my-token\'');
+      // Region placeholder should remain unchanged
+      expect(content).toContain('STORYBLOK_REGION');
     });
 
-    it('should show only token message when only token fails', async () => {
-      const saveError = new Error('Disk full');
-      mockedSaveToFile.mockRejectedValue(saveError);
+    it('should replace only region placeholder when token not provided', async () => {
+      vol.fromJSON({
+        '/test/project/src/environments/environment.ts': angularEnvTemplate,
+        '/test/project/src/environments/environment.development.ts': angularEnvTemplate,
+      });
 
-      const result = await handleEnvFileCreation('/test/project', 'test-token');
+      await updateAngularEnvironmentFiles('/test/project', undefined, 'us');
 
-      expect(result).toBe(false);
-      expect(mockedUI.warn).toHaveBeenCalledWith(
-        expect.stringContaining('Failed to create .env file'),
-      );
-      expect(mockedUI.info).toHaveBeenCalledWith(
-        expect.stringContaining('You can manually add STORYBLOK_DELIVERY_API_TOKEN'),
-      );
-      expect(mockedUI.info).not.toHaveBeenCalledWith(
-        expect.stringContaining('You can manually add STORYBLOK_REGION'),
-      );
+      const content = vol.readFileSync('/test/project/src/environments/environment.ts', 'utf-8');
+      expect(content).toContain('region: \'us\'');
+      // Token placeholder should remain unchanged
+      expect(content).toContain('STORYBLOK_DELIVERY_API_TOKEN');
     });
 
-    it('should show only region message when only region fails', async () => {
-      const saveError = new Error('Access denied');
-      mockedSaveToFile.mockRejectedValue(saveError);
+    it('should skip missing environment files silently and return empty array', async () => {
+      // No files exist in memfs
+      const result = await updateAngularEnvironmentFiles('/test/project', 'token', 'eu');
 
-      const result = await handleEnvFileCreation('/test/project', undefined, 'ca');
+      expect(result.updatedFiles).toEqual([]);
+    });
 
-      expect(result).toBe(false);
-      expect(mockedUI.warn).toHaveBeenCalledWith(
-        expect.stringContaining('Failed to create .env file'),
-      );
-      expect(mockedUI.info).not.toHaveBeenCalledWith(
-        expect.stringContaining('You can manually add STORYBLOK_DELIVERY_API_TOKEN'),
+    it('should return only the files that exist', async () => {
+      vol.fromJSON({
+        '/test/project/src/environments/environment.ts': angularEnvTemplate,
+        // environment.development.ts does not exist
+      });
+
+      const result = await updateAngularEnvironmentFiles('/test/project', 'token', 'eu');
+
+      expect(result.updatedFiles).toEqual(['/test/project/src/environments/environment.ts']);
+    });
+  });
+
+  describe('handleEnvFileCreation for Angular', () => {
+    const angularEnvTemplate = `export const environment = {
+  production: true,
+  accessToken: 'STORYBLOK_DELIVERY_API_TOKEN',
+  region: 'STORYBLOK_REGION',
+};`;
+
+    it('should update Angular environment files when template is angular', async () => {
+      vol.fromJSON({
+        '/test/project/src/environments/environment.ts': angularEnvTemplate,
+        '/test/project/src/environments/environment.development.ts': angularEnvTemplate,
+      });
+
+      const result = await handleEnvFileCreation('/test/project', 'my-token', 'eu', 'angular');
+
+      expect(result).toBe(true);
+      expect(mockedUI.ok).toHaveBeenCalledWith(
+        expect.stringContaining('Updated Angular environment files'),
+        true,
       );
+      // Verify files were actually updated
+      const content = vol.readFileSync('/test/project/src/environments/environment.ts', 'utf-8');
+      expect(content).toContain('accessToken: \'my-token\'');
+      expect(content).toContain('region: \'eu\'');
+    });
+
+    it('should return true and log info when no vars provided for angular', async () => {
+      const result = await handleEnvFileCreation('/test/project', undefined, undefined, 'angular');
+
+      expect(result).toBe(true);
+      expect(mockedUI.info).toHaveBeenCalledWith('No environment variables to write');
+    });
+
+    it('should log info when environment files do not exist', async () => {
+      // No Angular environment files exist
+      const result = await handleEnvFileCreation('/test/project', 'token', 'eu', 'angular');
+
+      expect(result).toBe(true);
       expect(mockedUI.info).toHaveBeenCalledWith(
-        expect.stringContaining('You can manually add STORYBLOK_REGION'),
+        'No Angular environment files found to update',
       );
     });
+
+    it('should create .env file for non-angular templates', async () => {
+      vol.fromJSON({
+        '/test/project/.gitkeep': '',
+      });
+
+      const result = await handleEnvFileCreation('/test/project', 'token', 'eu', 'react');
+
+      expect(result).toBe(true);
+      const content = vol.readFileSync('/test/project/.env', 'utf-8');
+      expect(content).toContain('STORYBLOK_DELIVERY_API_TOKEN=token');
+    });
   });
 
   it('should contain the correct region domains', () => {
diff --git a/packages/cli/src/commands/create/actions.ts b/packages/cli/src/commands/create/actions.ts
index b5438e2fb..76375c426 100644
--- a/packages/cli/src/commands/create/actions.ts
+++ b/packages/cli/src/commands/create/actions.ts
@@ -115,8 +115,89 @@ ${Object.entries(storyblokVars).map(([key, value]) => `${key}=${value}`).join('\
   }
 };
 
-// Helper to create .env file and handle errors
-export async function handleEnvFileCreation(resolvedPath: string, token?: string, region?: RegionCode): Promise<boolean> {
+/**
+ * Updates Angular environment files with Storyblok configuration
+ * Angular uses TypeScript environment files instead of .env files
+ * @param projectPath - The absolute path to the project directory
+ * @param token - The Storyblok access token
+ * @param region - The Storyblok region code
+ * @returns Object containing array of files that were actually updated
+ */
+export const updateAngularEnvironmentFiles = async (
+  projectPath: string,
+  token?: string,
+  region?: RegionCode,
+): Promise<{ updatedFiles: string[] }> => {
+  const environmentsDir = join(projectPath, 'src', 'environments');
+  const envFiles = ['environment.ts', 'environment.development.ts'];
+  const updatedFiles: string[] = [];
+
+  for (const envFile of envFiles) {
+    const filePath = join(environmentsDir, envFile);
+    try {
+      let content = await fs.readFile(filePath, 'utf-8');
+
+      // Replace placeholder values with actual values
+      if (token) {
+        content = content.replaceAll('STORYBLOK_DELIVERY_API_TOKEN', token);
+      }
+      if (region) {
+        content = content.replaceAll('STORYBLOK_REGION', region);
+      }
+
+      await saveToFile(filePath, content);
+      updatedFiles.push(filePath);
+    }
+    catch (error) {
+      const fsError = error as NodeJS.ErrnoException;
+      // If file doesn't exist, skip it silently
+      if (fsError.code === 'ENOENT') {
+        continue;
+      }
+      throw new Error(`Failed to update ${envFile}: ${(error as Error).message}`);
+    }
+  }
+
+  return { updatedFiles };
+};
+
+// Helper to create .env file (or Angular environment files) and handle errors
+export async function handleEnvFileCreation(resolvedPath: string, token?: string, region?: RegionCode, template?: string): Promise<boolean> {
+  // Angular uses TypeScript environment files instead of .env
+  if (template === 'angular') {
+    if (!token && !region) {
+      ui.info('No environment variables to write');
+      return true;
+    }
+    try {
+      const { updatedFiles } = await updateAngularEnvironmentFiles(resolvedPath, token, region);
+
+      if (updatedFiles.length === 0) {
+        ui.info('No Angular environment files found to update');
+        return true;
+      }
+
+      const writtenVars = [token && 'accessToken', region && 'region'].filter(Boolean).join(', ');
+      ui.ok(`Updated Angular environment files with: ${writtenVars}`, true);
+      return true;
+    }
+    catch (error) {
+      ui.warn(`Failed to update Angular environment files: ${(error as Error).message}`);
+      if (token) {
+        ui.info(
+          `You can manually add accessToken to src/environments/environment.ts and src/environments/environment.development.ts`,
+        );
+      }
+      if (region) {
+        ui.info(
+          `You can manually add region to src/environments/environment.ts and src/environments/environment.development.ts`,
+        );
+      }
+      return false;
+    }
+  }
+
+  // Default behavior for other frameworks: create .env file
   const envVars: Record<string, string> = {};
   if (token) {
     envVars.STORYBLOK_DELIVERY_API_TOKEN = token;
diff --git a/packages/cli/src/commands/create/index.test.ts b/packages/cli/src/commands/create/index.test.ts
index 687187001..bb3dc3a16 100644
--- a/packages/cli/src/commands/create/index.test.ts
+++ b/packages/cli/src/commands/create/index.test.ts
@@ -143,7 +143,7 @@ describe('createCommand', () => {
       // Should generate project
       expect(generateProject).toHaveBeenCalledWith('react', 'my-project', expect.any(String));
       // Should create .env file with provided token and session region
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'eu', 'react');
       // Should NOT create space or open browser
       expect(createSpace).not.toHaveBeenCalled();
       expect(openSpaceInBrowser).not.toHaveBeenCalled();
@@ -167,7 +167,7 @@ describe('createCommand', () => {
       // Should generate project
       expect(generateProject).toHaveBeenCalledWith('react', 'my-project', expect.any(String));
       // Should create .env file with provided token and region
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'us');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'us', 'react');
       // Should NOT create space, require authentication, or prompt for login
       expect(createSpace).not.toHaveBeenCalled();
       expect(requireAuthentication).not.toHaveBeenCalled();
@@ -411,7 +411,7 @@ describe('createCommand', () => {
       });
 
       // Verify .env file creation
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu', 'react');
 
       // Verify browser opening
       expect(openSpaceInBrowser).toHaveBeenCalledWith(12345, 'eu');
@@ -470,7 +470,7 @@ describe('createCommand', () => {
       await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react']);
 
       // Should call handleEnvFileCreation
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu', 'react');
       // Should continue with browser opening even if .env creation fails
       expect(openSpaceInBrowser).toHaveBeenCalled();
     });
@@ -587,7 +587,7 @@ describe('createCommand', () => {
       await createCommand.parseAsync(['node', 'test', './projects/my-project', '--template', 'react']);
 
       expect(generateProject).toHaveBeenCalledWith('react', 'my-project', expect.stringContaining('projects'));
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.stringContaining('my-project'), 'space-token-123', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.stringContaining('my-project'), 'space-token-123', 'eu', 'react');
     });
 
     it('should handle absolute paths correctly', async () => {
@@ -630,7 +630,7 @@ describe('createCommand', () => {
       // Verify space creation is skipped
       expect(createSpace).not.toHaveBeenCalled();
       // handleEnvFileCreation IS called with session region (eu from mock)
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'eu', 'react');
       expect(openSpaceInBrowser).not.toHaveBeenCalled();
 
       // Verify success message still shows
@@ -665,7 +665,7 @@ describe('createCommand', () => {
       // Verify space-related operations are skipped
       expect(createSpace).not.toHaveBeenCalled();
       // handleEnvFileCreation IS called with session region (eu from mock)
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'eu', 'vue');
       expect(openSpaceInBrowser).not.toHaveBeenCalled();
     });
 
@@ -1081,7 +1081,7 @@ describe('createCommand', () => {
       await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react', '--token', 'my-access-token', '--region', 'us']);
 
       // Should create .env file with provided token and region
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'us');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'us', 'react');
     });
 
     it('should validate region and show error for invalid region', async () => {
@@ -1117,7 +1117,7 @@ describe('createCommand', () => {
 
         expect(handleError).not.toHaveBeenCalled();
         expect(generateProject).toHaveBeenCalled();
-        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'token', region);
+        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'token', region, 'react');
       }
     });
 
@@ -1135,7 +1135,7 @@ describe('createCommand', () => {
       await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react']);
 
       // Should create .env file with space token and session region (eu by default in tests)
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu', 'react');
     });
 
     it('should not include region in .env when --token is provided without --region', async () => {
@@ -1148,7 +1148,7 @@ describe('createCommand', () => {
       await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react', '--token', 'my-access-token']);
 
       // Should create .env file with session region (eu from mock) when --region not provided
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-access-token', 'eu', 'react');
     });
 
     it('should work with --region and --skip-space flags together', async () => {
@@ -1165,7 +1165,7 @@ describe('createCommand', () => {
 
       // Should not create space but should call handleEnvFileCreation with only the region (no token)
       expect(createSpace).not.toHaveBeenCalled();
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'ca');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'ca', 'react');
     });
 
     it('should throw error when provided region does not match user account region during space creation', async () => {
@@ -1206,7 +1206,7 @@ describe('createCommand', () => {
       expect(handleError).not.toHaveBeenCalled();
       expect(generateProject).toHaveBeenCalled();
       expect(createSpace).toHaveBeenCalled();
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'space-token-123', 'eu', 'react');
     });
 
     it('should not throw region mismatch error when --token is provided with different region', async () => {
@@ -1222,7 +1222,7 @@ describe('createCommand', () => {
       // Should proceed without region mismatch error
       expect(handleError).not.toHaveBeenCalled();
       expect(generateProject).toHaveBeenCalled();
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-token', 'us');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-token', 'us', 'react');
 
       // Should not create space
       expect(createSpace).not.toHaveBeenCalled();
@@ -1244,7 +1244,7 @@ describe('createCommand', () => {
 
       // Should not create space but should call handleEnvFileCreation with undefined token and region
       expect(createSpace).not.toHaveBeenCalled();
-      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'us');
+      expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'us', 'react');
     });
 
     describe('session region fallback behavior', () => {
@@ -1258,7 +1258,7 @@ describe('createCommand', () => {
 
         await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react', '--token', 'my-token']);
 
-        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-token', 'us');
+        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-token', 'us', 'react');
       });
 
       it('should use CA session region as fallback when no --region provided with --skip-space', async () => {
@@ -1271,7 +1271,7 @@ describe('createCommand', () => {
 
         await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react', '--skip-space']);
 
-        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'ca');
+        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), undefined, 'ca', 'react');
       });
 
       it('should prioritize user-provided --region over session region', async () => {
@@ -1285,7 +1285,7 @@ describe('createCommand', () => {
         // User provides 'ap' region, should use that instead of 'us' session region
         await createCommand.parseAsync(['node', 'test', 'my-project', '--template', 'react', '--token', 'my-token', '--region', 'ap']);
 
-        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-token', 'ap');
+        expect(handleEnvFileCreation).toHaveBeenCalledWith(expect.any(String), 'my-token', 'ap', 'react');
       });
     });
   });
diff --git a/packages/cli/src/commands/create/index.ts b/packages/cli/src/commands/create/index.ts
index 6c0b8db3a..4a1cfe67b 100644
--- a/packages/cli/src/commands/create/index.ts
+++ b/packages/cli/src/commands/create/index.ts
@@ -209,14 +209,14 @@ export const createCommand = program
       let userData: User;
       let whereToCreateSpace = 'personal';
       if (token) {
-        await handleEnvFileCreation(resolvedPath, token, options.region || region);
+        await handleEnvFileCreation(resolvedPath, token, options.region || region, technologyTemplate);
         showNextSteps(technologyTemplate!, finalProjectPath);
         return;
       }
       if (options.skipSpace) {
         // Only create .env file if region is available (useful for configuring SDK)
         if (options.region || region) {
-          await handleEnvFileCreation(resolvedPath, undefined, options.region || region);
+          await handleEnvFileCreation(resolvedPath, undefined, options.region || region, technologyTemplate);
         }
         showNextSteps(technologyTemplate!, finalProjectPath);
         return;
@@ -303,7 +303,7 @@ export const createCommand = program
 
         // Create .env file with the Storyblok token
         if (createdSpace?.first_token) {
-          await handleEnvFileCreation(resolvedPath, createdSpace.first_token, region!);
+          await handleEnvFileCreation(resolvedPath, createdSpace.first_token, region!, technologyTemplate);
         }
 
         // Open the space in the browser
diff --git a/packages/cli/src/commands/types/generate/actions.test.ts b/packages/cli/src/commands/types/generate/actions.test.ts
index 6ef044162..febbd346a 100644
--- a/packages/cli/src/commands/types/generate/actions.test.ts
+++ b/packages/cli/src/commands/types/generate/actions.test.ts
@@ -1046,6 +1046,84 @@ describe('component property type annotations', () => {
   });
 });
 
+describe('single-option empty value', () => {
+  const opt = (values: string[], required: boolean, excludeEmpty: boolean) => ({
+    type: 'option' as const,
+    pos: 0,
+    required,
+    exclude_empty_option: excludeEmpty,
+    options: values.map(value => ({ name: value, value })),
+  });
+
+  const generate = async (schema: Record<string, unknown>) => {
+    const component: Component = {
+      name: 'test_component',
+      display_name: 'Test Component',
+      created_at: '2023-01-01T00:00:00Z',
+      updated_at: '2023-01-01T00:00:00Z',
+      id: 1,
+      schema,
+      internal_tags_list: [],
+      internal_tag_ids: [],
+    } as unknown as Component;
+    const spaceData: SpaceComponentsData = {
+      components: [component],
+      datasources: [],
+    } as unknown as SpaceComponentsData;
+    return (await generateTypes(spaceData, { strict: false })) as string;
+  };
+
+  // "" inclusion must be driven by `required`, never by `exclude_empty_option`
+  // (UI-only "Hide empty option"). Assert on the field's own union, not the
+  // `[k: string]: unknown` index signature (unrelated non-strict-mode behavior).
+
+  it('required field excludes "" regardless of exclude_empty_option', async () => {
+    const result = await generate({
+      first: opt(['one', 'two'], true, false),
+      second: opt(['one', 'two'], true, true),
+    });
+    expect(result).toContain('first: "one" | "two";');
+    expect(result).toContain('second: "one" | "two";');
+    expect(result).not.toContain('first: "" | "one" | "two"');
+  });
+
+  it('non-required field includes "" regardless of exclude_empty_option', async () => {
+    const result = await generate({
+      third: opt(['one', 'two'], false, false),
+      fourth: opt(['one', 'two'], false, true),
+    });
+    expect(result).toContain('third?: "" | "one" | "two";');
+    expect(result).toContain('fourth?: "" | "one" | "two";');
+  });
+
+  it('required field with a manual empty option still excludes ""', async () => {
+    const result = await generate({
+      fifth: opt(['one', 'two', ''], true, false),
+      sixth: opt(['one', 'two', ''], true, true),
+    });
+    expect(result).toContain('fifth: "one" | "two";');
+    expect(result).toContain('sixth: "one" | "two";');
+  });
+
+  it('non-required field with a manual empty option includes "" once', async () => {
+    const result = await generate({
+      seventh: opt(['one', 'two', ''], false, false),
+      eighth: opt(['one', 'two', ''], false, true),
+    });
+    expect(result).toContain('seventh?: "" | "one" | "two";');
+    expect(result).toContain('eighth?: "" | "one" | "two";');
+  });
+
+  it('multi-options mirrors the same required-driven "" behavior on items', async () => {
+    const result = await generate({
+      tags: { type: 'options', pos: 0, required: false, options: [{ name: 'one', value: 'one' }, { name: 'two', value: 'two' }] },
+      musts: { type: 'options', pos: 1, required: true, options: [{ name: 'one', value: 'one' }, { name: 'two', value: 'two' }] },
+    });
+    expect(result).toContain('tags?: ("" | "one" | "two")[];');
+    expect(result).toContain('musts: ("one" | "two")[];');
+  });
+});
+
 describe('generateStoryblokTypes', () => {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/packages/cli/src/commands/types/generate/actions.ts b/packages/cli/src/commands/types/generate/actions.ts
index 990ef3e6c..3a02d63d2 100644
--- a/packages/cli/src/commands/types/generate/actions.ts
+++ b/packages/cli/src/commands/types/generate/actions.ts
@@ -40,12 +40,17 @@ const getPropertyTypeAnnotation = (property: ComponentPropertySchema, prefix?: s
 
   let type: string | string[] = 'unknown';
 
-  const options = property.options && property.options.length > 0 ? property.options.map((item: { value: string }) => item.value) : [];
-
-  // Add empty option to options array
-  if (options.length > 0 && property.exclude_empty_option !== true) {
-    options.unshift('');
-  }
+  // Manual empty options behave like clearing the field, so normalize them out first,
+  // then decide whether "" is a reachable stored value based solely on `required`.
+  // `exclude_empty_option` ("Hide empty option") is a UI-only setting and must not
+  // affect the generated types.
+  const optionValues = property.options && property.options.length > 0
+    ? property.options.map((item: { value: string }) => item.value).filter(value => value !== '')
+    : [];
+
+  const options = optionValues.length > 0 && !property.required
+    ? ['', ...optionValues]
+    : optionValues;
 
   if (property.source === 'internal_stories') {
     // Only if there is a filter_content_type, we can return a proper type
diff --git a/packages/cli/src/lib/config/README.md b/packages/cli/src/lib/config/README.md
index 62f2c9f74..dc2c240ee 100644
--- a/packages/cli/src/lib/config/README.md
+++ b/packages/cli/src/lib/config/README.md
@@ -186,7 +186,7 @@ export default defineConfig({
     },
     types: {
       generate: {
-        output: 'storyblok-component-types.d.ts',
+        filename: 'storyblok-component-types.d.ts',
       },
     },
   },
diff --git a/packages/cli/src/lib/logger/logger-transport-file.test.ts b/packages/cli/src/lib/logger/logger-transport-file.test.ts
index 079244c28..645178c8e 100644
--- a/packages/cli/src/lib/logger/logger-transport-file.test.ts
+++ b/packages/cli/src/lib/logger/logger-transport-file.test.ts
@@ -1,5 +1,6 @@
-import { expect, it } from 'vitest';
+import { expect, it, vi } from 'vitest';
 import { vol } from 'memfs';
+import * as nodeFs from 'node:fs';
 import { FileTransport } from './logger-transport-file';
 import { APIError } from '../../utils/error';
 import { FetchError } from '../../utils/fetch';
@@ -55,3 +56,42 @@ it('should only keep n number of log files', () => {
   expect(fileContents.some(content => content?.includes('Log 4'))).toBe(true);
   expect(fileContents.some(content => content?.includes('Log 5'))).toBe(true);
 });
+
+it('should not throw when a pruned file was already removed by a concurrent process', () => {
+  vol.fromJSON({ './a.jsonl': 'a', './b.jsonl': 'b', './c.jsonl': 'c' });
+
+  // Simulate the race: between `readdirSync` and `unlinkSync` another CLI
+  // process deletes the same oldest file, so the first `unlinkSync` raises
+  // ENOENT. Pruning must swallow it and keep deleting the remaining files.
+  const enoent = Object.assign(new Error('ENOENT: no such file'), { code: 'ENOENT' });
+  const unlinkSpy = vi.spyOn(nodeFs, 'unlinkSync').mockImplementationOnce(() => {
+    throw enoent;
+  });
+
+  let deleted = 0;
+  expect(() => {
+    deleted = FileTransport.pruneLogFiles('.', 1, '.jsonl');
+  }).not.toThrow();
+
+  // Both targeted files (a.jsonl, b.jsonl) are gone after the call; only the
+  // most recent (c.jsonl) is kept.
+  expect(deleted).toBe(2);
+  const remaining = Object.keys(vol.toJSON()).map(p => p.split('/').pop()).sort();
+  expect(remaining).not.toContain('b.jsonl');
+  expect(remaining).toContain('c.jsonl');
+
+  unlinkSpy.mockRestore();
+});
+
+it('should rethrow non-ENOENT errors while pruning', () => {
+  vol.fromJSON({ './a.jsonl': 'a', './b.jsonl': 'b' });
+
+  const eacces = Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+  const unlinkSpy = vi.spyOn(nodeFs, 'unlinkSync').mockImplementationOnce(() => {
+    throw eacces;
+  });
+
+  expect(() => FileTransport.pruneLogFiles('.', 1, '.jsonl')).toThrow('EACCES');
+
+  unlinkSpy.mockRestore();
+});
diff --git a/packages/cli/src/lib/logger/logger-transport-file.ts b/packages/cli/src/lib/logger/logger-transport-file.ts
index 13c381cca..b6770a4d4 100644
--- a/packages/cli/src/lib/logger/logger-transport-file.ts
+++ b/packages/cli/src/lib/logger/logger-transport-file.ts
@@ -68,11 +68,24 @@ export class FileTransport implements LogTransport {
       return 0;
     }
 
+    let deleted = 0;
     for (const file of files.slice(0, filesToDelete)) {
-      unlinkSync(join(directory, file));
+      try {
+        unlinkSync(join(directory, file));
+      }
+      catch (error) {
+        // `readdirSync` and `unlinkSync` are not atomic, so a concurrent CLI
+        // process logging to the same directory may prune the same file first.
+        // The file is already gone, which is the desired outcome, so ignore it
+        // rather than letting best-effort log rotation crash the command.
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+          throw error;
+        }
+      }
+      deleted += 1;
     }
 
-    return filesToDelete;
+    return deleted;
   }
 
   public static listLogFiles(
diff --git a/packages/cli/src/types/index.ts b/packages/cli/src/types/index.ts
index 4594f8280..a1003f938 100644
--- a/packages/cli/src/types/index.ts
+++ b/packages/cli/src/types/index.ts
@@ -20,6 +20,11 @@ export type {
   DatasourceUpdate,
   InternalTag,
   Preset,
+  SharedAssetFolder,
+  SharedAssetFolderCreate,
+  SharedAssetFolderUpdate,
+  SharedInternalTag,
+  SharedInternalTagCreate,
   Space,
   SpaceCreate,
   SpaceUpdate,
diff --git a/packages/cli/src/utils/error/api-error.ts b/packages/cli/src/utils/error/api-error.ts
index c3ae46208..d8e99b08b 100644
--- a/packages/cli/src/utils/error/api-error.ts
+++ b/packages/cli/src/utils/error/api-error.ts
@@ -34,6 +34,15 @@ export const API_ACTIONS = {
   pull_asset_internal_tags: 'Failed to pull asset internal tags',
   push_asset_internal_tag: 'Failed to push asset internal tag',
   transfer_asset: 'Failed to transfer asset',
+  pull_shared_assets: 'Failed to pull library assets',
+  pull_shared_asset: 'Failed to pull library asset',
+  pull_shared_asset_folders: 'Failed to pull library folders',
+  pull_shared_asset_folder: 'Failed to pull library folder',
+  pull_shared_internal_tags: 'Failed to pull library tags',
+  push_shared_asset_create: 'Failed to create library asset',
+  push_shared_asset_update: 'Failed to update library asset',
+  push_shared_asset_folder: 'Failed to push library folder',
+  push_shared_internal_tag: 'Failed to push library tag',
   pull_datasources: 'Failed to pull datasources',
   push_datasource: 'Failed to push datasource',
   update_datasource: 'Failed to update datasource',
diff --git a/packages/cli/test/GUIDE.md b/packages/cli/test/GUIDE.md
index eb670f86f..b9b96eb8d 100644
--- a/packages/cli/test/GUIDE.md
+++ b/packages/cli/test/GUIDE.md
@@ -19,6 +19,45 @@ bash .claude/skills/qa-engineer-manual/scripts/seed-scenario.sh \
   --scenario-dir packages/cli/test/scenarios
 ```
 
+## Shared asset libraries
+
+A shared asset library is a top-level shared asset folder owned by the organization, with per-space read or write access. `assets pull` and `assets push` reach libraries through `--target` and `--library`. Library assets live under `.storyblok/assets/shared/<library_id>/`, parallel to the space subtree at `.storyblok/assets/<space_id>/`, each with its own `manifest.jsonl`.
+
+```bash
+# Pull only the readable libraries (writes .storyblok/assets/shared/<library_id>/).
+./dist/index.mjs assets pull --space $STORYBLOK_SPACE_ID --target shared
+
+# Pull the space plus every readable library.
+./dist/index.mjs assets pull --space $STORYBLOK_SPACE_ID --target all
+
+# Push a single file into a library (folder defaults to the library root).
+./dist/index.mjs assets push --space $STORYBLOK_SPACE_ID --target shared --library <libraryId> ./.storyblok/assets/shared/<libraryId>/qa-hero.png
+
+# Push every local library subtree present on disk.
+./dist/index.mjs assets push --space $STORYBLOK_SPACE_ID --target shared
+```
+
+Notes for manual testing:
+
+- A library must already exist before you can push to it. Libraries are root shared folders, which can only be created in org context (`POST /v1/orgs/{org_id}/shared_asset_folders` with `regions` and `asset_folder_access`), not from a space. Reuse an existing QA library when possible.
+- Shared-asset creation requires an `asset_folder_id` the space can write to. A library push defaults it to the library root, so `--folder` is optional.
+- The library root folder itself is skipped on bulk push (a space cannot push a root shared folder), while its child folders are pushed.
+- `--target` accepts only `space`, `shared`, or `auto` for push, and `with-referenced`, `all`, `space`, or `shared` for pull. Unknown values fail fast.
+
+### Cleaning up shared libraries safely
+
+Shared libraries are org-global, so you must never wipe them wholesale. The `--shared` cleanup is scoped by folder membership: it deletes every shared asset in the given library's folder tree, every internal tag scoped to the library, and every child folder, but never the library root or anything outside the library. Because it removes all content inside the library regardless of name, only run it against a dedicated QA library:
+
+```bash
+# Inspect a library.
+bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource shared-assets --library <libraryId>
+bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource shared-folders
+bash .claude/skills/qa-engineer-manual/scripts/list.sh --resource shared-tags --library <libraryId>
+
+# Delete all shared resources in the library's folder tree (assets, child folders, tags).
+bash .claude/skills/qa-engineer-manual/scripts/cleanup-remote.sh --shared --library <libraryId>
+```
+
 ## Known quirks
 
 - **Progress bar titles show `{title}` literally** — all progress bars render the raw `{title}` placeholder instead of the actual label. This is a known rendering issue and does not affect functionality. Ignore it when reading command output.
diff --git a/packages/eslint-config/package.json b/packages/eslint-config/package.json
index c2d63392a..77dde1f61 100644
--- a/packages/eslint-config/package.json
+++ b/packages/eslint-config/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/eslint-config",
   "type": "module",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Opinionated ESLint configuration for Storyblok ecosystem",
   "author": "Alvaro Saburido <hola@alvarosaburido.dev> (https://github.com/alvarosabu/)",
   "license": "MIT",
diff --git a/packages/js-client/package.json b/packages/js-client/package.json
index bd6cd51db..9ef7d0e37 100644
--- a/packages/js-client/package.json
+++ b/packages/js-client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "storyblok-js-client",
   "type": "module",
-  "version": "7.6.1",
+  "version": "7.7.0",
   "description": "Universal JavaScript SDK for Storyblok's API",
   "author": "Alexander Feiglstorfer <delooks@gmail.com>",
   "license": "MIT",
diff --git a/packages/js-client/src/index.test-d.ts b/packages/js-client/src/index.test-d.ts
new file mode 100644
index 000000000..3739e81bf
--- /dev/null
+++ b/packages/js-client/src/index.test-d.ts
@@ -0,0 +1,17 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import StoryblokClient from '.';
+import type { ISbResponse } from './interfaces';
+
+// Regression guard for DX-472: the write methods resolve to the `ISbResponse`
+// envelope (`{ data, status, statusText, headers }`), not the body payload
+// `ISbResponseData`. The created resource lives at `response.data.*`.
+describe('write method return types', () => {
+  const client = new StoryblokClient({ oauthToken: 'token' });
+
+  it('post/put/patch/delete resolve to ISbResponse', () => {
+    expectTypeOf(client.post).returns.resolves.toEqualTypeOf<ISbResponse>();
+    expectTypeOf(client.put).returns.resolves.toEqualTypeOf<ISbResponse>();
+    expectTypeOf(client.patch).returns.resolves.toEqualTypeOf<ISbResponse>();
+    expectTypeOf(client.delete).returns.resolves.toEqualTypeOf<ISbResponse>();
+  });
+});
diff --git a/packages/js-client/src/index.ts b/packages/js-client/src/index.ts
index 20521ec4d..0b95d8408 100755
--- a/packages/js-client/src/index.ts
+++ b/packages/js-client/src/index.ts
@@ -287,47 +287,47 @@ export class Storyblok {
     slug: string,
     params: ISbStoriesParams | ISbContentMangmntAPI = {},
     fetchOptions?: ISbCustomFetch,
-  ): Promise<ISbResponseData> {
+  ): Promise<ISbResponse> {
     const url = `/${slug}`;
 
     const rateLimit = determineRateLimit(undefined, undefined, this.rateLimitConfig, MANAGEMENT_API_DEFAULT_RATE_LIMIT);
-    return this.throttleManager.execute(rateLimit, 'post', url, params, fetchOptions) as Promise<ISbResponseData>;
+    return this.throttleManager.execute(rateLimit, 'post', url, params, fetchOptions) as Promise<ISbResponse>;
   }
 
   public put(
     slug: string,
     params: ISbStoriesParams | ISbContentMangmntAPI = {},
     fetchOptions?: ISbCustomFetch,
-  ): Promise<ISbResponseData> {
+  ): Promise<ISbResponse> {
     const url = `/${slug}`;
 
     const rateLimit = determineRateLimit(undefined, undefined, this.rateLimitConfig, MANAGEMENT_API_DEFAULT_RATE_LIMIT);
-    return this.throttleManager.execute(rateLimit, 'put', url, params, fetchOptions) as Promise<ISbResponseData>;
+    return this.throttleManager.execute(rateLimit, 'put', url, params, fetchOptions) as Promise<ISbResponse>;
   }
 
   public patch(
     slug: string,
     params: ISbStoriesParams | ISbContentMangmntAPI = {},
     fetchOptions?: ISbCustomFetch,
-  ): Promise<ISbResponseData> {
+  ): Promise<ISbResponse> {
     const url = `/${slug}`;
 
     const rateLimit = determineRateLimit(undefined, undefined, this.rateLimitConfig, MANAGEMENT_API_DEFAULT_RATE_LIMIT);
-    return this.throttleManager.execute(rateLimit, 'patch', url, params, fetchOptions) as Promise<ISbResponseData>;
+    return this.throttleManager.execute(rateLimit, 'patch', url, params, fetchOptions) as Promise<ISbResponse>;
   }
 
   public delete(
     slug: string,
     params: ISbStoriesParams | ISbContentMangmntAPI = {},
     fetchOptions?: ISbCustomFetch,
-  ): Promise<ISbResponseData> {
+  ): Promise<ISbResponse> {
     if (!params) {
       params = {} as ISbStoriesParams;
     }
     const url = `/${slug}`;
 
     const rateLimit = determineRateLimit(undefined, undefined, this.rateLimitConfig, MANAGEMENT_API_DEFAULT_RATE_LIMIT);
-    return this.throttleManager.execute(rateLimit, 'delete', url, params, fetchOptions) as Promise<ISbResponseData>;
+    return this.throttleManager.execute(rateLimit, 'delete', url, params, fetchOptions) as Promise<ISbResponse>;
   }
 
   public getStories(
diff --git a/packages/js-client/vitest.config.ts b/packages/js-client/vitest.config.ts
new file mode 100644
index 000000000..7550709a5
--- /dev/null
+++ b/packages/js-client/vitest.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    typecheck: {
+      enabled: true,
+      include: ['./src/**/*.test-d.ts'],
+    },
+  },
+});
diff --git a/packages/js/cypress.config.ts b/packages/js/cypress.config.ts
index 26f5546de..df1aba2a6 100644
--- a/packages/js/cypress.config.ts
+++ b/packages/js/cypress.config.ts
@@ -1,5 +1,7 @@
 import { defineConfig } from 'cypress';
 
 export default defineConfig({
-  e2e: {},
+  e2e: {
+    baseUrl: 'http://localhost:5173',
+  },
 });
diff --git a/packages/js/package.json b/packages/js/package.json
index 7fff4eb56..41bb58c66 100644
--- a/packages/js/package.json
+++ b/packages/js/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/js",
   "type": "module",
-  "version": "6.0.1",
+  "version": "6.2.0",
   "private": false,
   "description": "SDK to integrate Storyblok into your project using JavaScript.",
   "license": "MIT",
diff --git a/packages/js/src/editable.ts b/packages/js/src/editable.ts
index 48dea0d3f..8273fd34b 100644
--- a/packages/js/src/editable.ts
+++ b/packages/js/src/editable.ts
@@ -1,7 +1,5 @@
-import type { SbBlokData } from './types';
-
-export default (blok: SbBlokData) => {
-  if (typeof blok !== 'object' || typeof blok._editable === 'undefined') {
+export default (blok?: { _editable?: string }) => {
+  if (typeof blok !== 'object' || typeof blok._editable !== 'string') {
     return {};
   }
 
diff --git a/packages/live-preview/package.json b/packages/live-preview/package.json
index 8d6d33cae..e383cba74 100644
--- a/packages/live-preview/package.json
+++ b/packages/live-preview/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/live-preview",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Official Live Preview integration for the Storyblok Headless CMS",
   "author": "Storyblok",
diff --git a/packages/live-preview/src/editable.ts b/packages/live-preview/src/editable.ts
index e9256c61a..85efb5d9f 100644
--- a/packages/live-preview/src/editable.ts
+++ b/packages/live-preview/src/editable.ts
@@ -1,13 +1,11 @@
-import type { BlockContent } from './generated/types/field';
-
 interface EditableOptions {
   id: string;
   uid: string;
 }
 
-export default function storyblokEditable(block?: Pick<BlockContent, '_editable'>) {
+export default function storyblokEditable(block?: { _editable?: string }) {
   const editable = block?._editable;
-  if (!editable) {
+  if (typeof editable !== 'string' || !editable) {
     return {};
   }
 
diff --git a/packages/mapi-client/package.json b/packages/mapi-client/package.json
index 6a5d7f763..2451d0086 100644
--- a/packages/mapi-client/package.json
+++ b/packages/mapi-client/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/management-api-client",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Storyblok Management API Client",
   "author": "",
diff --git a/packages/mapi-client/src/index.ts b/packages/mapi-client/src/index.ts
index 05c656e65..b82e66f49 100644
--- a/packages/mapi-client/src/index.ts
+++ b/packages/mapi-client/src/index.ts
@@ -13,6 +13,9 @@ import { createDatasourcesResource } from './resources/datasources';
 import { createExperimentsResource } from './resources/experiments';
 import { createInternalTagsResource } from './resources/internal-tags';
 import { createPresetsResource } from './resources/presets';
+import { createSharedAssetFoldersResource } from './resources/shared-asset-folders';
+import { createSharedAssetsResource } from './resources/shared-assets';
+import { createSharedInternalTagsResource } from './resources/shared-internal-tags';
 import { createSpacesResource } from './resources/spaces';
 import { createStoriesResource } from './resources/stories';
 import { createUsersResource } from './resources/users';
@@ -181,6 +184,9 @@ export const createManagementApiClient = (config: ManagementApiClientConfig) =>
     post: httpPost,
     presets: createPresetsResource(deps),
     put: httpPut,
+    sharedAssetFolders: createSharedAssetFoldersResource(deps),
+    sharedAssets: createSharedAssetsResource(deps),
+    sharedInternalTags: createSharedInternalTagsResource(deps),
     spaces: createSpacesResource(deps),
     stories: createStoriesResource(deps),
     users: createUsersResource({ client, wrapRequest }),
@@ -189,6 +195,9 @@ export const createManagementApiClient = (config: ManagementApiClientConfig) =>
 
 export type ManagementApiClient = ReturnType<typeof createManagementApiClient>;
 
+export type { AccessLevel, AssetFolderAccess, SharedAssetFolder, SharedAssetFolderCreate, SharedAssetFolderGetResponse, SharedAssetFolderListResponse, SharedAssetFolderUpdate } from './resources/shared-asset-folders';
+export type { SharedAssetCreate, SharedAssetListQuery, SharedAssetListResponse, SharedAssetUploadRequest } from './resources/shared-assets';
+export type { SharedInternalTag, SharedInternalTagCreate, SharedInternalTagListQuery, SharedInternalTagListResponse, SharedInternalTagMutateResponse, SharedInternalTagObjectType } from './resources/shared-internal-tags';
 export type {
   ApiResponse,
   Asset,
diff --git a/packages/mapi-client/src/resources/assets.test.ts b/packages/mapi-client/src/resources/assets.test.ts
index af3afb49b..cc5da3afe 100644
--- a/packages/mapi-client/src/resources/assets.test.ts
+++ b/packages/mapi-client/src/resources/assets.test.ts
@@ -19,6 +19,31 @@ beforeAll(() => server.listen());
 afterEach(() => server.resetHandlers());
 afterAll(() => server.close());
 
+const preconditions = {
+  canCreateAssetWithSize({ space = '123' }: { space?: string } = {}) {
+    let signedBody: { filename?: string; size?: string } | undefined;
+    server.use(
+      http.post(`https://mapi.storyblok.com/v1/spaces/${space}/assets`, async ({ request }) => {
+        signedBody = await request.json() as { filename?: string; size?: string };
+        return HttpResponse.json({
+          id: 1,
+          post_url: 'https://s3.amazonaws.com/a.storyblok.com',
+          fields: { key: `f/${space}/${signedBody.size}/hash/${signedBody.filename}` },
+        });
+      }),
+      http.post('https://s3.amazonaws.com/a.storyblok.com', () => HttpResponse.json({})),
+      http.get(`https://mapi.storyblok.com/v1/spaces/${space}/assets/:asset_id/finish_upload`, () => HttpResponse.json({})),
+      http.get(`https://mapi.storyblok.com/v1/spaces/${space}/assets/:asset_id`, () => HttpResponse.json({
+        id: 1,
+        filename: `https://a.storyblok.com/f/${space}/2048x1820/hash/hero.png`,
+      })),
+    );
+    return {
+      getSignedBody: () => signedBody,
+    };
+  },
+};
+
 describe('assets.list()', () => {
   it('should successfully retrieve multiple assets', async () => {
     const client = createManagementApiClient({
@@ -75,6 +100,25 @@ describe('assets.list()', () => {
   });
 });
 
+describe('assets.create()', () => {
+  it('forwards the `size` field to the sign request so the CDN URL keeps its dimensions', async () => {
+    const { getSignedBody } = preconditions.canCreateAssetWithSize();
+    const client = createManagementApiClient({
+      personalAccessToken: 'test-token',
+      spaceId: 123,
+      region: 'eu',
+      rateLimit: false,
+    });
+
+    await client.assets.create({
+      body: { short_filename: 'hero.png', size: '2048x1820' },
+      file: new ArrayBuffer(0),
+    });
+
+    expect(getSignedBody()?.size).toBe('2048x1820');
+  });
+});
+
 describe('assets.convertToShared()', () => {
   it('should post to the convert endpoint with target_asset_folder_id and return the converted asset', async () => {
     let capturedUrl: string | undefined;
diff --git a/packages/mapi-client/src/resources/assets.ts b/packages/mapi-client/src/resources/assets.ts
index 64a8d3686..56aee50c7 100644
--- a/packages/mapi-client/src/resources/assets.ts
+++ b/packages/mapi-client/src/resources/assets.ts
@@ -55,8 +55,8 @@ export interface AssetUploadRequest {
 export type AssetCreate = AssetUpdate & AssetUploadRequest;
 
 /** Uploads the file to S3 using the signed fields from step 1. */
-async function uploadToS3(
-  signedResponse: SignResponseObjectResponses[200],
+export async function uploadToS3(
+  signedResponse: { post_url?: string; fields?: Record<string, unknown> },
   file: Blob | ArrayBuffer,
   filename: string,
 ): Promise<void> {
@@ -151,6 +151,8 @@ export function createAssetsResource(deps: MapiResourceDeps) {
           short_filename: body.short_filename,
           asset_folder_id: body.asset_folder_id,
           is_private: body.is_private,
+          size: body.size,
+          validate_upload: body.validate_upload,
         },
         file,
         signal,
diff --git a/packages/mapi-client/src/resources/shared-asset-folders.test.ts b/packages/mapi-client/src/resources/shared-asset-folders.test.ts
new file mode 100644
index 000000000..7504d26d2
--- /dev/null
+++ b/packages/mapi-client/src/resources/shared-asset-folders.test.ts
@@ -0,0 +1,41 @@
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { createManagementApiClient } from '../index';
+
+const server = setupServer();
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+const client = createManagementApiClient({ personalAccessToken: 'test-token', spaceId: 12345, region: 'eu', rateLimit: false });
+
+describe('sharedAssetFolders resource', () => {
+  it('lists shared asset folders for the active space with access levels', async () => {
+    server.use(
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders', () =>
+        HttpResponse.json({
+          shared_asset_folders: [
+            { id: 1, name: 'Brand', parent_id: null, uuid: 'u1', regions: ['eu'], asset_folder_access: [{ space_id: 12345, access_level: 'write' }] },
+          ],
+        })),
+    );
+
+    const { data } = await client.sharedAssetFolders.list();
+
+    expect(data?.shared_asset_folders?.[0]?.asset_folder_access?.[0]?.access_level).toBe('write');
+  });
+
+  it('creates a shared asset folder', async () => {
+    server.use(
+      http.post('https://mapi.storyblok.com/v1/spaces/12345/shared_asset_folders', async ({ request }) => {
+        const body = await request.json() as { shared_asset_folder: { name: string } };
+        return HttpResponse.json({ shared_asset_folder: { id: 9, name: body.shared_asset_folder.name, parent_id: null, uuid: 'u9' } }, { status: 201 });
+      }),
+    );
+
+    const { data } = await client.sharedAssetFolders.create({ body: { shared_asset_folder: { name: 'New' } } });
+
+    expect(data?.shared_asset_folder?.id).toBe(9);
+  });
+});
diff --git a/packages/mapi-client/src/resources/shared-asset-folders.ts b/packages/mapi-client/src/resources/shared-asset-folders.ts
new file mode 100644
index 000000000..275d8c35b
--- /dev/null
+++ b/packages/mapi-client/src/resources/shared-asset-folders.ts
@@ -0,0 +1,82 @@
+import type { ApiResponse, FetchOptions, MapiResourceDeps } from '../index';
+import { resolveSpaceId, type SpaceIdPathOverride } from './shared';
+
+export type AccessLevel = 'read' | 'write';
+
+export interface AssetFolderAccess {
+  space_id: number;
+  access_level: AccessLevel;
+}
+
+/**
+ * A shared (organization-level) asset folder. Top-level folders
+ * (`parent_id === null`) are "libraries"; per-space access is exposed via
+ * `asset_folder_access`. Not part of the generated SDK — these endpoints are
+ * issued as raw `client.*` calls.
+ */
+export interface SharedAssetFolder {
+  id: number;
+  name: string;
+  parent_id: number | null;
+  uuid: string;
+  parent_uuid?: string | null;
+  description?: string | null;
+  color?: string | null;
+  regions?: string[];
+  asset_folder_access?: AssetFolderAccess[];
+}
+
+export interface SharedAssetFolderCreate {
+  name: string;
+  parent_id?: number | null;
+  description?: string | null;
+  color?: string | null;
+  regions?: string[];
+  asset_folder_access?: AssetFolderAccess[];
+}
+
+export type SharedAssetFolderUpdate = Partial<SharedAssetFolderCreate>;
+
+export interface SharedAssetFolderListResponse {
+  shared_asset_folders: SharedAssetFolder[];
+}
+
+export interface SharedAssetFolderGetResponse {
+  shared_asset_folder: SharedAssetFolder;
+}
+
+export function createSharedAssetFoldersResource(deps: MapiResourceDeps) {
+  const { client, spaceId, wrapRequest } = deps;
+  const getSpaceId = (path?: SpaceIdPathOverride['path']) => resolveSpaceId(spaceId, path);
+  const kyOpts = (fetchOptions?: FetchOptions) =>
+    fetchOptions ? { kyOptions: { ...client.getConfig().kyOptions, ...fetchOptions } } : {};
+  const maybeThrow = (throwOnError?: boolean) => (throwOnError === undefined ? {} : { throwOnError });
+
+  return {
+    list<ThrowOnError extends boolean = false>(options: { query?: { search?: string; with_parent?: string; by_ids?: string }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride = {}): Promise<ApiResponse<SharedAssetFolderListResponse, ThrowOnError>> {
+      const { query, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedAssetFolderListResponse, ThrowOnError>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_asset_folders', path: { space_id: getSpaceId(path) }, query, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    get<ThrowOnError extends boolean = false>(folderId: number | string, options: { signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride = {}): Promise<ApiResponse<SharedAssetFolderGetResponse, ThrowOnError>> {
+      const { signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedAssetFolderGetResponse, ThrowOnError>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_asset_folders/{asset_folder_id}', path: { space_id: getSpaceId(path), asset_folder_id: folderId }, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    create<ThrowOnError extends boolean = false>(options: { body: { shared_asset_folder: SharedAssetFolderCreate }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<ApiResponse<SharedAssetFolderGetResponse, ThrowOnError>> {
+      const { body, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedAssetFolderGetResponse, ThrowOnError>(() =>
+        client.post({ url: '/v1/spaces/{space_id}/shared_asset_folders', path: { space_id: getSpaceId(path) }, body, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    update<ThrowOnError extends boolean = false>(folderId: number | string, options: { body: { shared_asset_folder: SharedAssetFolderUpdate }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<ApiResponse<void, ThrowOnError>> {
+      const { body, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<void, ThrowOnError>(() =>
+        client.put({ url: '/v1/spaces/{space_id}/shared_asset_folders/{asset_folder_id}', path: { space_id: getSpaceId(path), asset_folder_id: folderId }, body, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    delete<ThrowOnError extends boolean = false>(folderId: number | string, options: { query?: { recursive?: boolean }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride = {}): Promise<ApiResponse<void, ThrowOnError>> {
+      const { query, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<void, ThrowOnError>(() =>
+        client.delete({ url: '/v1/spaces/{space_id}/shared_asset_folders/{asset_folder_id}', path: { space_id: getSpaceId(path), asset_folder_id: folderId }, query, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+  };
+}
diff --git a/packages/mapi-client/src/resources/shared-assets.test.ts b/packages/mapi-client/src/resources/shared-assets.test.ts
new file mode 100644
index 000000000..4467da533
--- /dev/null
+++ b/packages/mapi-client/src/resources/shared-assets.test.ts
@@ -0,0 +1,42 @@
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { createManagementApiClient } from '../index';
+
+const server = setupServer();
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+const client = createManagementApiClient({ personalAccessToken: 'test-token', spaceId: 12345, region: 'eu', rateLimit: false });
+
+describe('sharedAssets resource', () => {
+  it('lists shared assets for a library', async () => {
+    server.use(
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_assets', ({ request }) => {
+        expect(new URL(request.url).searchParams.get('in_folder')).toBe('7');
+        return HttpResponse.json({ assets: [{ id: 1, filename: 'https://a.storyblok.com/f/12345/x.png', asset_folder_id: 7 }] }, { headers: { 'Total': '1', 'Per-Page': '100' } });
+      }),
+    );
+
+    const { data } = await client.sharedAssets.list({ query: { in_folder: 7 } });
+
+    expect(data?.assets?.[0]?.id).toBe(1);
+  });
+
+  it('creates a shared asset via sign -> S3 -> finish flow', async () => {
+    server.use(
+      http.post('https://mapi.storyblok.com/v1/spaces/12345/shared_assets', () =>
+        HttpResponse.json({ id: 55, post_url: 'https://s3.test/upload', fields: { 'key': 'g/1/x.png', 'Content-Type': 'image/png' } })),
+      http.post('https://s3.test/upload', () => new HttpResponse(null, { status: 204 })),
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_assets/55/finish_upload', () =>
+        HttpResponse.json({ id: 55, filename: 'https://a.storyblok.com/g/1/x.png' })),
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_assets/55', () =>
+        HttpResponse.json({ id: 55, filename: 'https://a.storyblok.com/g/1/x.png', asset_folder_id: 7 })),
+    );
+
+    const asset = await client.sharedAssets.create({ body: { short_filename: 'x.png', asset_folder_id: 7 }, file: new ArrayBuffer(4) });
+
+    expect(asset.id).toBe(55);
+  });
+});
diff --git a/packages/mapi-client/src/resources/shared-assets.ts b/packages/mapi-client/src/resources/shared-assets.ts
new file mode 100644
index 000000000..95a38d996
--- /dev/null
+++ b/packages/mapi-client/src/resources/shared-assets.ts
@@ -0,0 +1,142 @@
+import type { Asset, AssetUpdate } from '../generated/assets/types.gen';
+import type { ApiResponse, FetchOptions, MapiResourceDeps } from '../index';
+import { uploadToS3 } from './assets';
+import { resolveSpaceId, type SpaceIdPathOverride } from './shared';
+
+/**
+ * Fields for initiating a shared (org-level) asset upload. Mirrors the local
+ * asset upload request; `short_filename` maps to the server's `filename`.
+ */
+export interface SharedAssetUploadRequest {
+  short_filename: string;
+  id?: number;
+  asset_folder_id?: number;
+  is_private?: boolean;
+  size?: string;
+  validate_upload?: number;
+}
+
+export type SharedAssetCreate = AssetUpdate & SharedAssetUploadRequest;
+
+export interface SharedAssetListQuery {
+  in_folder?: number;
+  page?: number;
+  per_page?: number;
+  search?: string;
+  sort_by?: string;
+}
+
+export interface SharedAssetListResponse {
+  assets: Asset[];
+}
+
+interface SignResponse {
+  id?: number;
+  post_url?: string;
+  fields?: Record<string, unknown>;
+}
+
+/**
+ * Shared (organization-level) assets. These endpoints are not part of the
+ * generated SDK, so methods issue raw `client.*` calls. The active space must
+ * have read (list/get) or write (create/update/delete) access to the library.
+ */
+export function createSharedAssetsResource(deps: MapiResourceDeps) {
+  const { client, spaceId, wrapRequest } = deps;
+  const getSpaceId = (path?: SpaceIdPathOverride['path']) => resolveSpaceId(spaceId, path);
+  const kyOpts = (fetchOptions?: FetchOptions) =>
+    fetchOptions ? { kyOptions: { ...client.getConfig().kyOptions, ...fetchOptions } } : {};
+  const maybeThrow = (throwOnError?: boolean) => (throwOnError === undefined ? {} : { throwOnError });
+
+  return {
+    list<ThrowOnError extends boolean = false>(options: { query?: SharedAssetListQuery; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride = {}): Promise<ApiResponse<SharedAssetListResponse, ThrowOnError>> {
+      const { query, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedAssetListResponse, ThrowOnError>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_assets', path: { space_id: getSpaceId(path) }, query: query && { ...query }, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    get<ThrowOnError extends boolean = false>(assetId: number | string, options: { signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride = {}): Promise<ApiResponse<Asset, ThrowOnError>> {
+      const { signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<Asset, ThrowOnError>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: getSpaceId(path), asset_id: assetId }, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    /** Uploads a file to a shared library (sign → S3 → finish_upload → get). */
+    async upload(options: { body: SharedAssetUploadRequest; file: Blob | ArrayBuffer; signal?: AbortSignal; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<Asset> {
+      const { body, file, signal, path, fetchOptions } = options;
+      const { short_filename, ...rest } = body;
+      const resolvedSpaceId = getSpaceId(path);
+      const opts = kyOpts(fetchOptions);
+
+      const signResult = await wrapRequest<SignResponse, true>(() =>
+        client.post({ url: '/v1/spaces/{space_id}/shared_assets', path: { space_id: resolvedSpaceId }, query: { filename: short_filename, ...rest }, signal, throwOnError: true, ...opts }), true);
+      if (!signResult.data.id) {
+        throw new Error('Invalid signed response: missing id');
+      }
+      const assetId = signResult.data.id;
+
+      await uploadToS3(signResult.data, file, short_filename);
+
+      await wrapRequest<unknown, true>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}/finish_upload', path: { space_id: resolvedSpaceId, asset_id: assetId }, signal, throwOnError: true, ...opts }), true);
+
+      const getResult = await wrapRequest<Asset, true>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: resolvedSpaceId, asset_id: assetId }, signal, throwOnError: true, ...opts }), true);
+      return getResult.data;
+    },
+    /** Creates a shared asset (upload + metadata). Returns the resulting `Asset`. */
+    async create(options: { body: SharedAssetCreate; file: Blob | ArrayBuffer; signal?: AbortSignal; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<Asset> {
+      const { body, file, signal, path, fetchOptions } = options;
+      const resolvedSpaceId = getSpaceId(path);
+      const opts = kyOpts(fetchOptions);
+
+      const asset = await this.upload({
+        body: { short_filename: body.short_filename, asset_folder_id: body.asset_folder_id, is_private: body.is_private },
+        file,
+        signal,
+        path: { space_id: resolvedSpaceId },
+        fetchOptions,
+      });
+
+      const { short_filename, asset_folder_id, is_private, size, validate_upload, ...metadata } = body;
+      const hasMetadata = Object.values(metadata).some(v => v !== undefined && v !== null);
+      if (hasMetadata) {
+        await wrapRequest<void, true>(() =>
+          client.put({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: resolvedSpaceId, asset_id: asset.id }, body: { asset: { ...metadata, asset_folder_id } }, signal, throwOnError: true, ...opts }), true);
+        const updated = await wrapRequest<Asset, true>(() =>
+          client.get({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: resolvedSpaceId, asset_id: asset.id }, signal, throwOnError: true, ...opts }), true);
+        return updated.data;
+      }
+      return asset;
+    },
+    /** Updates a shared asset's metadata, optionally replacing the file. */
+    async update(assetId: number | string, options: ({ body: { asset: AssetUpdate }; file?: undefined } | { body: { asset: AssetUpdate; short_filename: string }; file: Blob | ArrayBuffer }) & { signal?: AbortSignal; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<void> {
+      const { body, file, signal, path, fetchOptions } = options;
+      const resolvedSpaceId = getSpaceId(path);
+      const opts = kyOpts(fetchOptions);
+
+      if (file !== undefined) {
+        const { short_filename, ...assetBody } = body as { short_filename: string; asset: AssetUpdate };
+        const signResult = await wrapRequest<SignResponse, true>(() =>
+          client.post({ url: '/v1/spaces/{space_id}/shared_assets', path: { space_id: resolvedSpaceId }, query: { filename: short_filename, id: Number(assetId) }, signal, throwOnError: true, ...opts }), true);
+        if (!signResult.data.id) {
+          throw new Error('Invalid signed response: missing id');
+        }
+        await uploadToS3(signResult.data, file, short_filename);
+        await wrapRequest<unknown, true>(() =>
+          client.get({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}/finish_upload', path: { space_id: resolvedSpaceId, asset_id: signResult.data.id }, signal, throwOnError: true, ...opts }), true);
+        if (assetBody.asset && Object.keys(assetBody.asset).length > 0) {
+          await wrapRequest<void, true>(() =>
+            client.put({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: resolvedSpaceId, asset_id: assetId }, body: assetBody, signal, throwOnError: true, ...opts }), true);
+        }
+      }
+      else {
+        await wrapRequest<void, true>(() =>
+          client.put({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: resolvedSpaceId, asset_id: assetId }, body, signal, throwOnError: true, ...opts }), true);
+      }
+    },
+    delete<ThrowOnError extends boolean = false>(assetId: number | string, options: { signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride = {}): Promise<ApiResponse<Asset, ThrowOnError>> {
+      const { signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<Asset, ThrowOnError>(() =>
+        client.delete({ url: '/v1/spaces/{space_id}/shared_assets/{asset_id}', path: { space_id: getSpaceId(path), asset_id: assetId }, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+  };
+}
diff --git a/packages/mapi-client/src/resources/shared-internal-tags.test.ts b/packages/mapi-client/src/resources/shared-internal-tags.test.ts
new file mode 100644
index 000000000..fbcff6fdd
--- /dev/null
+++ b/packages/mapi-client/src/resources/shared-internal-tags.test.ts
@@ -0,0 +1,40 @@
+import { http, HttpResponse } from 'msw';
+import { setupServer } from 'msw/node';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { createManagementApiClient } from '../index';
+
+const server = setupServer();
+beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+
+const client = createManagementApiClient({ personalAccessToken: 'test-token', spaceId: 12345, region: 'eu', rateLimit: false });
+
+describe('sharedInternalTags resource', () => {
+  it('lists tags scoped to a library via asset_folder_id', async () => {
+    server.use(
+      http.get('https://mapi.storyblok.com/v1/spaces/12345/shared_internal_tags', ({ request }) => {
+        expect(new URL(request.url).searchParams.get('asset_folder_id')).toBe('7');
+        return HttpResponse.json({ internal_tags: [{ id: 3, name: 'hero', object_type: 'asset' }] });
+      }),
+    );
+
+    const { data } = await client.sharedInternalTags.list({ query: { asset_folder_id: 7 } });
+
+    expect(data?.internal_tags?.[0]?.name).toBe('hero');
+  });
+
+  it('creates a tag with asset_folder_id in the body', async () => {
+    server.use(
+      http.post('https://mapi.storyblok.com/v1/spaces/12345/shared_internal_tags', async ({ request }) => {
+        const body = await request.json() as { shared_internal_tag: { asset_folder_id: number } };
+        expect(body.shared_internal_tag.asset_folder_id).toBe(7);
+        return HttpResponse.json({ internal_tag: { id: 4, name: 'new', object_type: 'asset' } });
+      }),
+    );
+
+    const { data } = await client.sharedInternalTags.create({ body: { shared_internal_tag: { name: 'new', object_type: 'asset', asset_folder_id: 7 } } });
+
+    expect(data?.internal_tag?.id).toBe(4);
+  });
+});
diff --git a/packages/mapi-client/src/resources/shared-internal-tags.ts b/packages/mapi-client/src/resources/shared-internal-tags.ts
new file mode 100644
index 000000000..b40c079c1
--- /dev/null
+++ b/packages/mapi-client/src/resources/shared-internal-tags.ts
@@ -0,0 +1,72 @@
+import type { ApiResponse, FetchOptions, MapiResourceDeps } from '../index';
+import { resolveSpaceId, type SpaceIdPathOverride } from './shared';
+
+export type SharedInternalTagObjectType = 'asset' | 'component' | 'idea';
+
+export interface SharedInternalTag {
+  id: number;
+  name: string;
+  object_type: SharedInternalTagObjectType;
+  assets_count?: number;
+}
+
+export interface SharedInternalTagCreate {
+  name: string;
+  object_type: SharedInternalTagObjectType;
+  /** The library root folder the tag is scoped to. Required on every call. */
+  asset_folder_id: number;
+}
+
+export interface SharedInternalTagListQuery {
+  /** The library root folder. Required. */
+  asset_folder_id: number;
+  search?: string;
+  by_object_type?: string;
+  by_ids?: string;
+  page?: number;
+  per_page?: number;
+}
+
+export interface SharedInternalTagListResponse {
+  internal_tags: SharedInternalTag[];
+}
+
+export interface SharedInternalTagMutateResponse {
+  internal_tag: SharedInternalTag;
+}
+
+/**
+ * Shared (organization-level) internal tags, scoped to a library. Every method
+ * carries `asset_folder_id` = library root (query param on list/delete, body
+ * field on create/update). Not part of the generated SDK — raw `client.*`.
+ */
+export function createSharedInternalTagsResource(deps: MapiResourceDeps) {
+  const { client, spaceId, wrapRequest } = deps;
+  const getSpaceId = (path?: SpaceIdPathOverride['path']) => resolveSpaceId(spaceId, path);
+  const kyOpts = (fetchOptions?: FetchOptions) =>
+    fetchOptions ? { kyOptions: { ...client.getConfig().kyOptions, ...fetchOptions } } : {};
+  const maybeThrow = (throwOnError?: boolean) => (throwOnError === undefined ? {} : { throwOnError });
+
+  return {
+    list<ThrowOnError extends boolean = false>(options: { query: SharedInternalTagListQuery; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<ApiResponse<SharedInternalTagListResponse, ThrowOnError>> {
+      const { query, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedInternalTagListResponse, ThrowOnError>(() =>
+        client.get({ url: '/v1/spaces/{space_id}/shared_internal_tags', path: { space_id: getSpaceId(path) }, query: { ...query }, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    create<ThrowOnError extends boolean = false>(options: { body: { shared_internal_tag: SharedInternalTagCreate }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<ApiResponse<SharedInternalTagMutateResponse, ThrowOnError>> {
+      const { body, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedInternalTagMutateResponse, ThrowOnError>(() =>
+        client.post({ url: '/v1/spaces/{space_id}/shared_internal_tags', path: { space_id: getSpaceId(path) }, body, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    update<ThrowOnError extends boolean = false>(tagId: number, options: { body: { shared_internal_tag: SharedInternalTagCreate }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<ApiResponse<SharedInternalTagMutateResponse, ThrowOnError>> {
+      const { body, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<SharedInternalTagMutateResponse, ThrowOnError>(() =>
+        client.patch({ url: '/v1/spaces/{space_id}/shared_internal_tags/{internal_tag_id}', path: { space_id: getSpaceId(path), internal_tag_id: tagId }, body, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+    delete<ThrowOnError extends boolean = false>(tagId: number, options: { query: { asset_folder_id: number }; signal?: AbortSignal; throwOnError?: ThrowOnError; fetchOptions?: FetchOptions } & SpaceIdPathOverride): Promise<ApiResponse<void, ThrowOnError>> {
+      const { query, signal, path, throwOnError, fetchOptions } = options;
+      return wrapRequest<void, ThrowOnError>(() =>
+        client.delete({ url: '/v1/spaces/{space_id}/shared_internal_tags/{internal_tag_id}', path: { space_id: getSpaceId(path), internal_tag_id: tagId }, query, signal, ...maybeThrow(throwOnError), ...kyOpts(fetchOptions) }), throwOnError);
+    },
+  };
+}
diff --git a/packages/migrations/package.json b/packages/migrations/package.json
index 15453f7f8..6e603523c 100644
--- a/packages/migrations/package.json
+++ b/packages/migrations/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/migrations",
   "type": "module",
-  "version": "0.1.16",
+  "version": "0.2.1",
   "private": false,
   "description": "Migration utilities for Storyblok",
   "author": "Storyblok",
diff --git a/packages/nuxt/package.json b/packages/nuxt/package.json
index e369a0fa7..3759ebea8 100644
--- a/packages/nuxt/package.json
+++ b/packages/nuxt/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/nuxt",
   "type": "module",
-  "version": "11.0.1",
+  "version": "11.1.1",
   "description": "Storyblok Nuxt module",
   "homepage": "https://github.com/storyblok/monoblok/tree/main/packages/nuxt#readme",
   "repository": {
diff --git a/packages/openapi/package.json b/packages/openapi/package.json
index d55cc6d26..26d37b0d8 100644
--- a/packages/openapi/package.json
+++ b/packages/openapi/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@storyblok/openapi",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Storyblok Management API OpenAPI specifications",
   "private": true,
   "scripts": {
diff --git a/packages/react/README.md b/packages/react/README.md
index 155d502ff..5d14265ef 100755
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -233,24 +233,27 @@ export async function fetchData() {
 
 | Export                 | Use Case                            | Live Editing | Static Export Support |
 | ---------------------- | ----------------------------------- | ------------ | --------------------- |
-| `@storyblok/react`     | Client-side rendering, SPA          | ✅            | ✅                     |
-| `@storyblok/react/ssr` | Server-side rendering, static sites | ❌            | ✅                     |
-| `@storyblok/react/rsc` | React Server Components             | ✅            | ❌                     |
+| `@storyblok/react`     | Client-side rendering, SPA          | ✅           | ✅                    |
+| `@storyblok/react/ssr` | Server-side rendering, static sites | ❌           | ✅                    |
+| `@storyblok/react/rsc` | React Server Components             | ✅           | ❌                    |
 
 ### When to Use Each Export
 
 **Use `@storyblok/react`** for:
+
 - Single Page Applications (SPA)
 - Client-side rendered React apps
 - When you need live editing in browser-based applications
 
 **Use `@storyblok/react/ssr`** for:
+
 - Next.js static exports (`output: 'export'`)
 - Static site generation without live editing
 - Server-side rendering where live editing isn't required
 - Performance-critical scenarios where bundle size matters
 
 **Use `@storyblok/react/rsc`** for:
+
 - Next.js App Router with React Server Components
 - When you need live editing with server components
 - Modern React applications with server/client component separation
@@ -265,7 +268,7 @@ If you're using Next.js with `output: 'export'` for static site generation, you
 // next.config.js
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  output: 'export', // Enables static export
+  output: "export", // Enables static export
 };
 
 module.exports = nextConfig;
@@ -306,7 +309,7 @@ export default async function Home() {
 
 export async function fetchData() {
   const storyblokApi = getStoryblokApi();
-  return storyblokApi.get(`cdn/stories/home`, { version: 'draft' });
+  return storyblokApi.get(`cdn/stories/home`, { version: "draft" });
 }
 ```
 
@@ -386,6 +389,7 @@ export async function fetchData() {
 ```
 
 **The `StoryblokStory` component automatically:**
+
 - Renders your Storyblok content components on the server
 - Loads the bridge script for live editing (when in Visual Editor)
 - Handles live content updates via global cache
@@ -396,9 +400,9 @@ export async function fetchData() {
 You can pass bridge options for advanced configurations:
 
 ```jsx
-const bridgeOptions = { resolveRelations: ['article.author'] };
+const bridgeOptions = { resolveRelations: ["article.author"] };
 
-<StoryblokStory story={data.story} bridgeOptions={bridgeOptions} />
+<StoryblokStory story={data.story} bridgeOptions={bridgeOptions} />;
 ```
 
 **Advanced: Manual Component Separation**
@@ -421,6 +425,7 @@ import { StoryblokServerComponent, StoryblokLiveEditing } from '@storyblok/react
 When creating your individual Storyblok content components (like `Page`, `Teaser`, etc.), you must use `StoryblokServerComponent` for nested components. Import it from the same export you're using:
 
 **For RSC (with live editing):**
+
 ```jsx
 import {
   storyblokEditable,
@@ -439,6 +444,7 @@ export default Page;
 ```
 
 **For SSR (static exports):**
+
 ```jsx
 import {
   storyblokEditable,
@@ -698,10 +704,18 @@ For a comprehensive list of options you can provide to the `useStoryblokRichText
 You can override the default resolvers by passing a `resolvers` prop to the `StoryblokRichText` component, for example, to use NextJS Link component or add a custom codeblok component:
 
 ```ts
-import { StoryblokRichText, useStoryblok, MarkTypes, type StoryblokRichTextNode } from '@storyblok/react';
+import { StoryblokRichText, useStoryblok, MarkTypes, type SbReactRichTextComponentMap, type SbReactRichTextProps } from '@storyblok/react';
 import Link from 'next/link';
 import CodeBlock from './components/CodeBlock';
 
+function CustomLink({ children, attrs }: SbReactRichTextProps<"link">) {
+  return (
+    <Link href={attrs?.href ?? ""} target={attrs?.target ?? "_self"}>
+      {children}
+    </Link>
+  );
+}
+
 function App() {
   const story = useStoryblok('home', { version: 'draft' });
 
@@ -709,40 +723,16 @@ function App() {
     return <div>Loading...</div>;
   }
 
-  const resolvers = {
-     [MarkTypes.LINK]: (node: StoryblokRichTextNode<ReactElement>) => {
-      return node.attrs?.linktype === 'story'
-         ? (
-            <Link
-              href={node.attrs?.href}
-              target={node.attrs?.target}
-            >
-              {node.text}
-            </Link>
-          )
-        : (
-            <a
-              href={node.attrs?.href}
-              target={node.attrs?.target}
-            >
-              {node.text}
-            </a>
-          );
-    },
-    [BlockTypes.CODE_BLOCK]: (node) =>
-      <CodeBlock
-        class={node?.attrs?.class}
-      >
-        {node.children}
-      </CodeBlock>;
-  }
+  const components: SbReactRichTextComponentMap = {
+    heading: CustomHeading,
+    link: CustomLink,
+    table: CustomTable,
+    bold: ({ children }) => <b className="font-bold text-black">{children}</b>,
+  };
 
   return (
     <div>
-      <StoryblokRichText
-        doc={story.content.richText}
-        resolvers={resolvers}
-      />
+      <StoryblokRichText document={blok.richtext_field} components={components} />
     </div>
   );
 }
@@ -867,6 +857,7 @@ By using these techniques, you can ensure that only the necessary components and
 ### "Server Actions are not supported with static export"
 
 **Error:** When using Next.js with `output: 'export'`, you might encounter:
+
 ```
 Error: Server Actions are not supported with static export
 ```
@@ -901,8 +892,8 @@ Error: Server Actions are not supported with static export
 ```js
 storyblokInit({
   components: {
-    page: Page,        // Matches 'page' component in Storyblok
-    teaser: Teaser,    // Matches 'teaser' component in Storyblok
+    page: Page, // Matches 'page' component in Storyblok
+    teaser: Teaser, // Matches 'teaser' component in Storyblok
     // Add all your components here
   },
 });
diff --git a/packages/react/package.json b/packages/react/package.json
index a680416e8..081507d7a 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/react",
   "type": "module",
-  "version": "7.0.1",
+  "version": "7.2.0",
   "private": false,
   "description": "SDK to integrate Storyblok into your project using React.",
   "author": "Storyblok",
@@ -30,6 +30,21 @@
       "types": "./dist/rsc.d.ts",
       "import": "./dist/rsc.mjs",
       "require": "./dist/rsc.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.mjs",
+      "require": "./dist/next.js"
+    },
+    "./next/rsc": {
+      "types": "./dist/next/rsc.d.ts",
+      "import": "./dist/next/rsc.mjs",
+      "require": "./dist/next/rsc.js"
+    },
+    "./next/client": {
+      "types": "./dist/next/client.d.ts",
+      "import": "./dist/next/client.mjs",
+      "require": "./dist/next/client.js"
     }
   },
   "main": "./dist/index.js",
@@ -68,7 +83,9 @@
     }
   },
   "dependencies": {
+    "@storyblok/api-client": "workspace:*",
     "@storyblok/js": "workspace:*",
+    "@storyblok/live-preview": "workspace:*",
     "@storyblok/richtext": "workspace:*"
   },
   "devDependencies": {
diff --git a/packages/react/src/__tests__/richtext.test.tsx b/packages/react/src/__tests__/richtext.test.tsx
index 8c6fbffab..7036e322c 100644
--- a/packages/react/src/__tests__/richtext.test.tsx
+++ b/packages/react/src/__tests__/richtext.test.tsx
@@ -7,6 +7,8 @@ import CustomHeading from './richtext/CustomHeading';
 import CustomLink from './richtext/CustomLink';
 import CustomCodeBlock from './richtext/CodeComponent';
 import CustomTable from './richtext/CustomTable';
+import CustomText from './richtext/CustomText';
+import HeadingWithRichText from './richtext/HeadingWithRichText';
 
 interface AttributePositionRule {
   key: string;
@@ -200,5 +202,21 @@ describe('react StoryblokRichText component', () => {
       const { container } = render(<StoryblokRichText wrapper={false} document={table.input} components={options} />);
       expect(alignImageSrcAttribute(container.innerHTML)).toBe(table.expected);
     });
+    const text_node = customRendererFixture.text_node;
+    it(text_node.title, () => {
+      const options: SbReactRichTextComponentMap = {
+        text: CustomText,
+      };
+      const { container } = render(<StoryblokRichText wrapper={false} document={text_node.input} components={options} data={{ prefix: '[prefix]' }} />);
+      expect(alignImageSrcAttribute(container.innerHTML)).toBe(text_node.expected);
+    });
+    const infinite_loop = customRendererFixture.infinite_loop_prevention;
+    it(infinite_loop.title, () => {
+      const options: SbReactRichTextComponentMap = {
+        heading: HeadingWithRichText,
+      };
+      const { container } = render(<StoryblokRichText wrapper={false} document={infinite_loop.input} components={options} />);
+      expect(alignImageSrcAttribute(container.innerHTML)).toBe(infinite_loop.expected);
+    });
   });
 });
diff --git a/packages/react/src/__tests__/richtext/CustomText.tsx b/packages/react/src/__tests__/richtext/CustomText.tsx
new file mode 100644
index 000000000..b4ed83761
--- /dev/null
+++ b/packages/react/src/__tests__/richtext/CustomText.tsx
@@ -0,0 +1,13 @@
+import type { SbReactRichTextProps } from '@storyblok/react';
+
+export default function CustomText({ text, context }: SbReactRichTextProps<'text'>) {
+  const data = context?.data as { prefix: string } | undefined;
+  const prefix = data?.prefix ?? '';
+  return (
+    <>
+      {prefix}
+      {' '}
+      {text.toUpperCase()}
+    </>
+  );
+}
diff --git a/packages/react/src/__tests__/richtext/HeadingWithRichText.tsx b/packages/react/src/__tests__/richtext/HeadingWithRichText.tsx
new file mode 100644
index 000000000..b7254cfcd
--- /dev/null
+++ b/packages/react/src/__tests__/richtext/HeadingWithRichText.tsx
@@ -0,0 +1,18 @@
+/**
+ * Custom heading component that internally uses StoryblokRichText.
+ * This tests the infinite loop prevention - without it, this would cause:
+ * HeadingWithRichText -> StoryblokRichText -> HeadingWithRichText -> ...
+ */
+import type { SbReactRichTextProps } from '@storyblok/react';
+import { StoryblokRichText } from '@storyblok/react';
+import type { JSX } from 'react';
+
+export default function HeadingWithRichText({ content, attrs, context }: SbReactRichTextProps<'heading'>) {
+  const level = attrs?.level || 1;
+  const Tag = `h${level}` as keyof JSX.IntrinsicElements;
+  return (
+    <Tag data-type="recursive-heading" data-level={attrs?.level}>
+      {content && <StoryblokRichText wrapper={false} document={content} {...context} />}
+    </Tag>
+  );
+}
diff --git a/packages/react/src/core/create-storyblok-richtext.tsx b/packages/react/src/core/create-storyblok-richtext.tsx
index 892cb6e36..14930b16f 100644
--- a/packages/react/src/core/create-storyblok-richtext.tsx
+++ b/packages/react/src/core/create-storyblok-richtext.tsx
@@ -21,6 +21,7 @@ export function createStoryblokRichText(
     document,
     optimizeImage,
     components,
+    data,
     wrapper = true,
     ...rest
   }: SbRichTextProps): ReactNode {
@@ -30,6 +31,7 @@ export function createStoryblokRichText(
         blok: DefaultBlok,
         ...components,
       },
+      data,
     });
 
     const content = render(document);
diff --git a/packages/react/src/core/rich-text-renderer.tsx b/packages/react/src/core/rich-text-renderer.tsx
index 29c2786fa..af903eda8 100644
--- a/packages/react/src/core/rich-text-renderer.tsx
+++ b/packages/react/src/core/rich-text-renderer.tsx
@@ -25,6 +25,7 @@ export type SbReactRichTextComponentMap = {
 export interface SbReactRichTextRenderContext {
   optimizeImage?: boolean | SbRichTextImageOptions;
   components?: SbReactRichTextComponentMap;
+  data?: unknown;
 }
 export interface StoryblokRichTextProps extends SbReactRichTextRenderContext {
   optimizeImage?: boolean | SbRichTextImageOptions;
@@ -82,7 +83,7 @@ function renderLinkGroup(
   const Custom = resolveComponent(linkMark.type, options.components);
   if (Custom) {
     return (
-      <Custom key={key} {...linkMark}>
+      <Custom key={key} {...linkMark} context={options}>
         {inner}
       </Custom>
     );
@@ -97,18 +98,27 @@ function renderLinkGroup(
 }
 
 function renderNode(node: SbRichTextNode, options: SbReactRichTextRenderContext, key: React.Key): ReactNode {
-  if (node.type === 'text') {
-    return renderTextNode(node as SbRichTextTextNode, options, key);
-  }
+  const content = node.type !== 'text' && node.content ? renderChildren(node.content, options) : null;
+
+  // Custom renderer takes full control
   const Custom = resolveComponent(node.type, options.components);
 
   if (Custom) {
+    // When passing context to a custom component, exclude that component type
+    // to prevent infinite loops if the custom component uses StoryblokRichText internally
+    const contextForCustom = options.components?.[node.type]
+      ? { ...options, components: { ...options.components, [node.type]: undefined } }
+      : options;
     return (
-      <Custom key={key} {...node} context={options}>
-        {node.content ? renderChildren(node.content, options) : null}
+      <Custom key={key} {...node} context={contextForCustom}>
+        {content}
       </Custom>
     );
   }
+
+  if (node.type === 'text') {
+    return renderTextNode(node as SbRichTextTextNode, options, key);
+  }
   const tag = resolveTag(node);
   if (!tag) {
     return node.content ? renderChildren(node.content, options) : null;
@@ -249,7 +259,7 @@ function renderTextNodeWithMarks(
 function wrapMark(children: ReactNode, mark: SbRichTextMark, options: SbReactRichTextRenderContext): ReactNode {
   const Custom = resolveComponent(mark.type, options.components);
   if (Custom) {
-    return <Custom {...mark}>{children}</Custom>;
+    return <Custom {...mark} context={options}>{children}</Custom>;
   }
 
   const tag = resolveTag(mark);
diff --git a/packages/react/src/v2/StoryblokRichText.tsx b/packages/react/src/v2/StoryblokRichText.tsx
new file mode 100644
index 000000000..6fb8ac9d3
--- /dev/null
+++ b/packages/react/src/v2/StoryblokRichText.tsx
@@ -0,0 +1,16 @@
+import { createRichTextRenderer } from '.';
+import type { ReactNode } from 'react';
+import type { StoryblokRichTextProps } from '../core/richtext';
+
+export function StoryblokRichText({
+  document,
+  optimizeImage,
+  components,
+}: StoryblokRichTextProps): ReactNode {
+  const render = createRichTextRenderer({
+    optimizeImage,
+    components,
+  });
+  const content = render(document);
+  return content;
+};
diff --git a/packages/react/src/v2/client/StoryblokPreview.tsx b/packages/react/src/v2/client/StoryblokPreview.tsx
new file mode 100644
index 000000000..6bb37c668
--- /dev/null
+++ b/packages/react/src/v2/client/StoryblokPreview.tsx
@@ -0,0 +1,52 @@
+'use client';
+
+import { onStoryblokEditorEvent } from '@storyblok/live-preview';
+import type { Story } from '@storyblok/api-client';
+import {
+  type ReactNode,
+  useEffect,
+  useState,
+} from 'react';
+
+export interface StoryblokPreviewProps {
+  /**
+   * Initial story fetched by the application.
+   */
+  story: Story;
+
+  /**
+   * Render function that receives the latest story.
+   */
+  children: (story: Story) => ReactNode;
+}
+
+export function StoryblokPreview({
+  story,
+  children,
+}: StoryblokPreviewProps) {
+  const [currentStory, setCurrentStory] = useState(story);
+  useEffect(() => {
+    let mounted = true;
+    let unsubscribe: (() => void) | undefined;
+
+    const setup = async () => {
+      unsubscribe = await onStoryblokEditorEvent((updatedStory) => {
+        if (!mounted) {
+          return;
+        }
+        setCurrentStory(updatedStory as Story);
+      });
+    };
+
+    setup();
+
+    return () => {
+      mounted = false;
+      unsubscribe?.();
+    };
+  }, []);
+
+  return <>{children(currentStory)}</>;
+}
+
+export default StoryblokPreview;
diff --git a/packages/react/src/v2/client/index.ts b/packages/react/src/v2/client/index.ts
new file mode 100644
index 000000000..373bd9554
--- /dev/null
+++ b/packages/react/src/v2/client/index.ts
@@ -0,0 +1 @@
+export { default as StoryblokPreview } from './StoryblokPreview';
diff --git a/packages/react/src/v2/component-registry.tsx b/packages/react/src/v2/component-registry.tsx
new file mode 100644
index 000000000..9dc5e5d08
--- /dev/null
+++ b/packages/react/src/v2/component-registry.tsx
@@ -0,0 +1,138 @@
+import { type ComponentType, type ReactNode, Suspense } from 'react';
+import type { SbBlokData } from '.';
+
+/** Internal type: how the registry calls components (always passes SbBlokData) */
+type StoryblokComponentType = ComponentType<{ block: SbBlokData }>;
+
+/**
+ * Registration type: accepts any component whose block prop is a subtype of SbBlokData.
+ * Using `any` here intentionally avoids contravariance errors — components that declare
+ * specific block shapes (e.g. `Block<"feature">`) are valid entries.
+ */
+type AnyBlokComponent = ComponentType<{ block: any }>;
+
+/**
+ * Component entry that supports async components with Suspense.
+ * Can be either a plain component or a config object with fallback.
+ */
+export type ComponentEntry =
+  | AnyBlokComponent
+  | {
+    component: AnyBlokComponent;
+    /** Custom fallback for this component's Suspense boundary */
+    fallback?: ReactNode;
+    /** Whether to wrap in Suspense (auto-detected for lazy components, can be forced) */
+    suspense?: boolean;
+  };
+
+export interface RegistryConfig {
+  components: Record<string, ComponentEntry>;
+  /** Fallback component when a blok type is not found */
+  fallback?: AnyBlokComponent;
+  /** Default Suspense fallback for async components */
+  suspenseFallback?: ReactNode;
+}
+
+export interface RegistryResult {
+  StoryblokComponent: ComponentType<{ block: SbBlokData } & Record<string, unknown>>;
+  StoryblokBlocks: ComponentType<{ blocks: SbBlokData[] } & Record<string, unknown>>;
+  resolve: (name: string) => StoryblokComponentType | null;
+}
+
+/** Default fallback shown while async components load */
+function DefaultSuspenseFallback(): ReactNode {
+  return null;
+}
+
+/**
+ * Check if a component is a lazy component (created with React.lazy).
+ * Lazy components have $$typeof Symbol(react.lazy).
+ */
+function isLazyComponent(component: unknown): boolean {
+  if (typeof component !== 'object' || component === null) {
+    return false;
+  }
+  const typedComponent = component as { $$typeof?: symbol };
+  return (
+    typeof typedComponent.$$typeof === 'symbol'
+    && typedComponent.$$typeof.toString() === 'Symbol(react.lazy)'
+  );
+}
+
+/**
+ * Normalize a component entry to extract component and config.
+ */
+function normalizeEntry(entry: ComponentEntry): {
+  component: StoryblokComponentType;
+  fallback?: ReactNode;
+  suspense?: boolean;
+} {
+  if (typeof entry === 'function' || isLazyComponent(entry)) {
+    return { component: entry as StoryblokComponentType };
+  }
+  return entry;
+}
+
+export function createRegistry(config: RegistryConfig): RegistryResult {
+  const defaultSuspenseFallback = config.suspenseFallback ?? (
+    <DefaultSuspenseFallback />
+  );
+
+  const resolve = (name: string): StoryblokComponentType | null => {
+    const entry = config.components[name];
+    if (!entry) {
+      return config.fallback ?? null;
+    }
+    return normalizeEntry(entry).component;
+  };
+
+  function StoryblokComponent({ block, ...rest }: { block: SbBlokData } & Record<string, unknown>): ReactNode {
+    const entry = config.components[block.component];
+
+    if (!entry) {
+      if (config.fallback) {
+        const FallbackComponent = config.fallback;
+        return <FallbackComponent block={block} {...rest} />;
+      }
+      console.warn(`[Storyblok] Unknown component: ${block.component}`);
+      return null;
+    }
+
+    const { component: Component, fallback, suspense } = normalizeEntry(entry);
+
+    // Determine if we should wrap in Suspense:
+    // - Explicitly set via suspense option
+    // - Auto-detected for lazy components
+    const needsSuspense = suspense ?? isLazyComponent(Component);
+
+    if (needsSuspense) {
+      return (
+        <Suspense fallback={fallback ?? defaultSuspenseFallback}>
+          <Component block={block} {...rest} />
+        </Suspense>
+      );
+    }
+
+    return <Component block={block} {...rest} />;
+  }
+
+  function StoryblokBlocks({ blocks, ...rest }: { blocks: SbBlokData[] } & Record<string, unknown>): ReactNode {
+    if (!blocks || blocks.length === 0) {
+      return null;
+    }
+
+    return (
+      <>
+        {blocks.map(block => (
+          <StoryblokComponent key={block._uid} block={block} {...rest} />
+        ))}
+      </>
+    );
+  }
+
+  return {
+    StoryblokComponent,
+    StoryblokBlocks,
+    resolve,
+  };
+}
diff --git a/packages/react/src/v2/guide.md b/packages/react/src/v2/guide.md
new file mode 100644
index 000000000..6b1330818
--- /dev/null
+++ b/packages/react/src/v2/guide.md
@@ -0,0 +1,512 @@
+# Using `@storyblok/react/next` with Next.js App Router
+
+This guide explains how `@storyblok/react/next` works, how it is wired up in this project, and how to handle real-world patterns: async components with slow fetches, live preview, and mixing client interactivity with server-rendered content.
+
+> **Playground:** A fully working Next.js App Router example using this SDK is available at
+> [github.com/dipankarmaikap/nextjs-storyblok-react-sdk-v2](https://github.com/dipankarmaikap/nextjs-storyblok-react-sdk-v2).
+> All code snippets in this guide are taken from that repository.
+
+---
+
+## Table of Contents
+
+- [Using `@storyblok/react/next` with Next.js App Router](#using-storyblokreactnext-with-nextjs-app-router)
+  - [Table of Contents](#table-of-contents)
+  - [0. Installation](#0-installation)
+  - [1. Setup: client and registry](#1-setup-client-and-registry)
+  - [2. Rendering a page](#2-rendering-a-page)
+  - [3. Production vs. preview: the two-deployment strategy](#3-production-vs-preview-the-two-deployment-strategy)
+    - [How it works](#how-it-works)
+    - [How the page reacts to `isPreview`](#how-the-page-reacts-to-ispreview)
+  - [4. Live preview with `StoryblokPreview`](#4-live-preview-with-storyblokpreview)
+  - [5. Async components with slow fetches — WeatherWidget](#5-async-components-with-slow-fetches--weatherwidget)
+    - [The problem](#the-problem)
+    - [The solution: `suspense: true` in the registry](#the-solution-suspense-true-in-the-registry)
+    - [The component](#the-component)
+    - [Caching strategy](#caching-strategy)
+    - [The skeleton](#the-skeleton)
+  - [6. Client interactivity — Accordion (the right pattern)](#6-client-interactivity--accordion-the-right-pattern)
+    - [The challenge](#the-challenge)
+    - [The pattern: Server Component wrapper + Client Component shell](#the-pattern-server-component-wrapper--client-component-shell)
+    - [Why this works](#why-this-works)
+  - [7. The broken pattern — why you cannot import server code inside a Client Component](#7-the-broken-pattern--why-you-cannot-import-server-code-inside-a-client-component)
+    - [Why this fails at build time](#why-this-fails-at-build-time)
+    - [The rule](#the-rule)
+
+---
+
+## 0. Installation
+
+This guide uses a prerelease build published via [pkg.pr.new](https://pkg.pr.new). Install it directly by URL — no registry publish required:
+
+```bash
+npm i https://pkg.pr.new/@storyblok/react@a76b1c7
+```
+
+This installs the exact commit that the guide is written against.
+
+---
+
+## 1. Setup: client and registry
+
+Everything starts in `app/lib/storyblok.tsx`. Three things are created here:
+
+**`isPreview`** — a module-level boolean that is `true` on the preview deployment and `false` on production. It is evaluated once per cold start and stays fixed for the lifetime of the process.
+
+**`createApiClient`** — a typed wrapper around the Storyblok Delivery API. On the preview deployment, `cache: { strategy: "network-first" }` is set so every request goes to Storyblok directly, bypassing the in-memory cache. On production, the default cache-first strategy (60 s TTL) applies.
+
+**`createRegistry`** — maps Storyblok component names (as defined in your space) to React components. It also accepts per-component Suspense configuration.
+
+```tsx
+// app/lib/storyblok.tsx
+import { createApiClient, createRegistry } from '@storyblok/react/next';
+
+/**
+ * True on the preview deployment (STORYBLOK_ENV=preview).
+ * False on production (env var absent or set to any other value).
+ *
+ * This is a module-level constant: it is evaluated once per cold start and
+ * stays fixed for the lifetime of the process. Use it everywhere you need
+ * to branch between "show draft content + live editing" and "show published
+ * content + full caching".
+ */
+export const isPreview = process.env.STORYBLOK_ENV === 'preview';
+
+export const client = createApiClient({
+  accessToken: process.env.NEXT_PUBLIC_STORYBLOK_DELIVERY_API_TOKEN!,
+  region: process.env.NEXT_PUBLIC_STORYBLOK_REGION as 'us' | 'eu',
+  // On the preview deployment, bypass the in-memory cache so every request
+  // fetches the latest draft content from Storyblok directly.
+  // On production, the default cache-first strategy (60 s TTL) applies.
+  ...(isPreview && { cache: { strategy: 'network-first' } }),
+});
+
+export const { StoryblokComponent, StoryblokBlocks } = createRegistry({
+  components: {
+    page: Page,
+    grid: Grid,
+    teaser: Teaser,
+    feature: Feature,
+    product_list: ProductList,
+    accordion: Accordion,
+
+    // Components that are async and slow get a suspense boundary + skeleton:
+    weather_widget: {
+      component: WeatherWidget,
+      fallback: <WeatherWidgetSkeleton />,
+      suspense: true,
+    },
+  },
+  fallback: FallbackBlock, // rendered when no match is found
+});
+```
+
+- **`StoryblokComponent`** renders a single blok by looking up its `component` field in the registry.
+- **`StoryblokBlocks`** iterates an array of bloks and renders each one via `StoryblokComponent`.
+- When `suspense: true` is set, the registry automatically wraps the component in a `<Suspense>` boundary using the provided `fallback`. This means a slow component will stream in after the skeleton, without blocking the rest of the page.
+
+---
+
+## 2. Rendering a page
+
+The recommended pattern uses a catch-all route `app/[[...slug]]/page.tsx` to handle every URL in the app.
+
+Because Next.js 16 makes `params` a `Promise`, slug access is deferred inside a `<Suspense>` boundary to keep the outer component synchronous (static shell). `PageContent` then suspends on the Storyblok fetch.
+
+**`StoryContent`** is a small Server Component that acts as a single source of truth for how a story is rendered. It is used in two places: the initial server render in `page.tsx`, and inside the `renderContent` Server Action called by `StoryblokPreview` on live editor updates. Keeping the layout markup in one place means you never have to keep two callsites in sync.
+
+```tsx
+// app/components/StoryContent.tsx
+import type { Story } from '@storyblok/react/next';
+import { StoryblokComponent } from '../lib/storyblok';
+
+export function StoryContent({ story }: { story: Story }) {
+  return (
+    <main>
+      <StoryblokComponent blok={story.content} />
+    </main>
+  );
+}
+```
+
+```tsx
+// app/[[...slug]]/page.tsx
+import { Suspense } from 'react';
+import { StoryblokPreview } from '@storyblok/react/next/rsc';
+import { renderContent } from '../lib/actions';
+import { client, isPreview } from '../lib/storyblok';
+import { StoryContent } from '../components/StoryContent';
+
+type Params = Promise<{ slug?: string[] }>;
+
+/**
+ * Optional catch-all route — handles every URL in the app.
+ *
+ * slug segments   → Storyblok story slug
+ * /               → undefined          → "home"
+ * /about          → ["about"]          → "about"
+ * /blog/my-post   → ["blog","my-post"] → "blog/my-post"
+ *
+ * In Next.js 16 `params` is a Promise, so slug access is pushed inside
+ * a <Suspense> boundary to keep the outer component sync (static shell).
+ * PageContent then suspends for the Storyblok fetch.
+ */
+export default function CatchAllPage({ params }: { params: Params }) {
+  return (
+    <Suspense>
+      {params.then(({ slug }) => {
+        const storySlug = slug?.join('/') ?? 'home';
+        const storyPromise = client.stories.get(storySlug, {
+          query: { version: isPreview ? 'draft' : 'published' },
+        });
+        return <PageContent storyPromise={storyPromise} />;
+      })}
+    </Suspense>
+  );
+}
+
+async function PageContent({
+  storyPromise,
+}: {
+  storyPromise: ReturnType<typeof client.stories.get>;
+}) {
+  const { data } = await storyPromise;
+  const story = data?.story;
+
+  if (!story) {
+    return <main>Story not found</main>;
+  }
+
+  const content = <StoryContent story={story} />;
+
+  // In production: return pre-rendered content directly
+  if (!isPreview) {
+    return content;
+  }
+
+  // On the preview deployment: wrap in StoryblokPreview for live updates
+  return (
+    <>
+      <div style={{ background: 'yellow', padding: '10px' }}>
+        PREVIEW MODE IS ON
+      </div>
+      <StoryblokPreview renderContent={renderContent}>
+        {content}
+      </StoryblokPreview>
+    </>
+  );
+}
+```
+
+The `renderContent` Server Action is kept in a separate file so it can be passed as a serialisable reference to `StoryblokPreview`:
+
+```tsx
+// app/lib/actions.tsx
+'use server';
+
+import type { ReactNode } from 'react';
+import type { Story } from '@storyblok/react/next';
+import { StoryContent } from '../components/StoryContent';
+
+export async function renderContent(story: Story): Promise<ReactNode> {
+  return <StoryContent story={story} />;
+}
+```
+
+> `renderContent` must be a **Server Action** (`"use server"`) because `StoryblokPreview` is a Client Component that needs to call it over the network when the editor sends a content update.
+
+---
+
+## 3. Production vs. preview: the two-deployment strategy
+
+Rather than using Next.js Draft Mode cookies to toggle preview on a single deployment, the recommended approach is **two separate deployments of the same codebase** driven by a single environment variable.
+
+### How it works
+
+| Deployment | `STORYBLOK_ENV`            | `isPreview` | Story version | API cache                      | Live editing            |
+| ---------- | -------------------------- | ----------- | ------------- | ------------------------------ | ----------------------- |
+| Production | unset (or any other value) | `false`     | `published`   | cache-first (60 s TTL)         | off                     |
+| Preview    | `"preview"`                | `true`      | `draft`       | `network-first` (always fresh) | on (`StoryblokPreview`) |
+
+Set `STORYBLOK_ENV=preview` only in the environment variables of your preview deployment (e.g. a Vercel preview environment or a separate Vercel project). The production deployment does not set this variable.
+
+**Why two deployments instead of a cookie?**
+
+- **No per-request branching.** `isPreview` is a module-level constant evaluated at cold start. The production render path is entirely free of preview-related code — no cookie reads, no `draftMode()` calls, no conditional fetches.
+- **Predictable caching.** The production deployment can rely on stable Next.js Data Cache behaviour. The preview deployment opts fully out of caching (`network-first`) so editors always see their latest save.
+- **Simpler ops.** Each deployment has a clear, single purpose. There is no risk of a user accidentally accessing draft content on the production URL because the token that enables preview is never set there.
+
+**Configure the Visual Editor preview URL** in your Storyblok space settings to point at the preview deployment URL. The production URL stays clean.
+
+### How the page reacts to `isPreview`
+
+```
+isPreview === false  →  fetch published  →  return static content
+isPreview === true   →  fetch draft      →  return StoryblokPreview (listens for editor messages)
+```
+
+---
+
+## 4. Live preview with `StoryblokPreview`
+
+`StoryblokPreview` is a Client Component exported from `@storyblok/react/next/rsc`. It:
+
+- Receives the initially server-rendered content as **`children`** so the page is not blank on first load.
+- Listens for `postMessage` events from the Storyblok Visual Editor iframe.
+- When the editor sends an updated story, calls your `renderContent` Server Action, re-renders the content on the server, and swaps in the new React tree.
+- **Debounces** editor events (default 300 ms) so rapid keystrokes do not each fire a separate Server Action call.
+
+```tsx
+<StoryblokPreview renderContent={renderContent}>{content}</StoryblokPreview>;
+```
+
+**Props**
+
+| Prop            | Type                                   | Required | Default | Description                                                                    |
+| --------------- | -------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------ |
+| `renderContent` | `(story: Story) => Promise<ReactNode>` | ✓        | —       | Server Action called on each editor update                                     |
+| `children`      | `ReactNode`                            | ✓        | —       | Initial server-rendered content                                                |
+| `debounceMs`    | `number`                               | —        | `300`   | Milliseconds to wait after the last editor event before triggering a re-render |
+
+## 5. Async components with slow fetches — WeatherWidget
+
+### The problem
+
+Some Storyblok bloks need data from external APIs or databases. If a weather API takes 10 seconds to respond, you do not want the entire page to block.
+
+### The solution: `suspense: true` in the registry
+
+When you register a component with `suspense: true` and a `fallback`, the registry wraps it in a `<Suspense>` boundary. The page streams HTML to the browser immediately with the skeleton visible. Once the async component finishes, React flushes the real content.
+
+```tsx
+// app/lib/storyblok.tsx
+export const { StoryblokComponent, StoryblokBlocks } = createRegistry({
+  components: {
+    weather_widget: {
+      component: WeatherWidget,
+      fallback: <WeatherWidgetSkeleton />,
+      suspense: true,
+    },
+  },
+});
+```
+
+### The component
+
+`WeatherWidget` is a plain `async` Server Component. It calls `getWeather`, which routes through the cache layers below.
+
+```tsx
+// app/components/WeatherWidget.tsx
+export async function WeatherWidget({ blok }: WeatherWidgetProps) {
+  const weatherData = await getWeather(blok.location ?? '');
+
+  return (
+    <div {...storyblokEditable(blok)}>
+      <h3>{blok.title}</h3>
+      <p>
+        {weatherData.temperature}
+        °C —
+        {weatherData.windSpeed}
+        {' '}
+        km/h
+      </p>
+    </div>
+  );
+}
+```
+
+### Caching strategy
+
+Weather data is fetched from an external API that is completely independent of Storyblok story content. Because of this, the same cache is used on both the production and preview deployments. There is no reason to bypass it in preview — doing so would cause a slow skeleton flash on every editor change even though the weather data has not changed.
+
+Three layers work together:
+
+| Layer              | API     | Scope                      | Purpose                                                                      |
+| ------------------ | ------- | -------------------------- | ---------------------------------------------------------------------------- |
+| `react.cache()`    | React   | Single request             | Deduplicates calls within one render (e.g. two bloks with the same location) |
+| `unstable_cache()` | Next.js | Cross-request (Data Cache) | Persists results across requests, 60 s TTL                                   |
+| Raw fetch          | —       | —                          | The slow external API call (simulated at 10 s)                               |
+
+```tsx
+// Layer 1 — raw fetch (slow, no caching)
+async function fetchWeatherData(location: string): Promise<WeatherData> {
+  // calls external weather API …
+}
+
+// Layer 2 — cross-request cache (Next.js Data Cache, 60-second TTL)
+//
+// unstable_cache persists results to the Next.js Data Cache (disk-backed)
+// so entries survive across requests and serverless instances.
+// Used on both production and preview — weather data is external and
+// independent of Storyblok story content, so bypassing it in preview
+// would cause a needless skeleton flash on every editor change.
+const getCachedWeather = unstable_cache(fetchWeatherData, ['weather'], {
+  revalidate: 60,
+});
+
+// Layer 3 — request deduplication (React cache)
+//
+// react.cache() deduplicates calls within a single render pass.
+// If two WeatherWidget bloks on the same page share the same location,
+// only one cache lookup is made for the entire request.
+const getWeather = cache(getCachedWeather);
+```
+
+The `network-first` strategy set on `createApiClient` for the preview deployment only bypasses the **Storyblok API client's** internal cache (story JSON). It does not affect `unstable_cache` or `react.cache()` used by `WeatherWidget` — those remain intact on both deployments.
+
+### The skeleton
+
+`WeatherWidgetSkeleton` renders a pulse animation with the same layout as the real widget, so there is no layout shift when the data arrives.
+
+```tsx
+// app/components/WeatherWidgetSkeleton.tsx
+export function WeatherWidgetSkeleton() {
+  return (
+    <div className="rounded-lg border border-zinc-700 bg-zinc-900 p-6">
+      <div className="animate-pulse">
+        <div className="h-6 w-40 rounded bg-zinc-800" />
+        {/* ... matching layout placeholders ... */}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## 6. Client interactivity — Accordion (the right pattern)
+
+### The challenge
+
+The Accordion needs `useState` for open/close behaviour — that means it must be a Client Component. But its body is a Storyblok `body` field containing nested bloks, which may include Server Components that fetch from a database.
+
+You cannot render Server Components inside a Client Component. But you _can_ pass pre-rendered Server Component output as `children`.
+
+### The pattern: Server Component wrapper + Client Component shell
+
+The solution splits the work into two files:
+
+**`AccordionShell.tsx` — Client Component**
+
+Handles only UI state. It knows nothing about Storyblok bloks or server-only code. It receives its content as `children` and shows or hides it.
+
+```tsx
+// app/components/patterns/AccordionShell.tsx
+'use client';
+
+import { type ReactNode, useState } from 'react';
+import { type SbBlokData, storyblokEditable } from '@storyblok/react/next';
+
+export function AccordionShell({ title, children, blok, defaultOpen = false }) {
+  const [open, setOpen] = useState(defaultOpen);
+
+  return (
+    <section {...storyblokEditable(blok)}>
+      <button onClick={() => setOpen(!open)}>{title}</button>
+      {open && <div>{children}</div>}
+    </section>
+  );
+}
+```
+
+**`Accordion.tsx` — Server Component wrapper**
+
+Registered in the component registry. It runs on the server, renders the `body` bloks via `StoryblokBlocks`, and passes the result as `children` to `AccordionShell`.
+
+```tsx
+// app/components/Accordion.tsx
+import { AccordionShell } from './patterns/AccordionShell';
+import { StoryblokBlocks } from '../lib/storyblok';
+
+export function Accordion({ blok }) {
+  return (
+    <AccordionShell
+      title={blok.title || 'Accordion'}
+      defaultOpen={blok.default_open}
+      blok={blok}
+    >
+      {/* StoryblokBlocks executes on the server.
+          The rendered output is passed as children — not the component reference. */}
+      {blok.body?.length ? <StoryblokBlocks blocks={blok.body} /> : null}
+    </AccordionShell>
+  );
+}
+```
+
+### Why this works
+
+When React processes `Accordion` (a Server Component), it renders `StoryblokBlocks` and resolves all nested components — including any that query a database — entirely on the server. The result is serialised HTML (React's server payload). That payload is what gets passed as `children` to `AccordionShell`.
+
+By the time `AccordionShell` runs on the client, `children` is already a chunk of inert HTML. The client component is just toggling visibility — it never touches server-only code.
+
+```
+Server                           Client
+------                           ------
+Accordion
+  └─ StoryblokBlocks            (resolves here)
+       └─ ProductList
+            └─ ProductRows
+                 └─ db.ts       (server-only, fine)
+  └─ AccordionShell ──────────> AccordionShell
+       children = <html.../>         useState(open)
+                                     {open && children}
+```
+
+---
+
+## 7. The broken pattern — why you cannot import server code inside a Client Component
+
+`app/components/_BrokenAccordion.example.tsx` demonstrates what goes wrong when you skip the wrapper pattern.
+
+```tsx
+// _BrokenAccordion.example.tsx (commented out — DO NOT USE)
+'use client';
+
+import { StoryblokBlocks } from '../lib/storyblok'; // <-- THIS BREAKS THE BUILD
+
+export function BrokenAccordion({ blok }) {
+  const [open, setOpen] = useState(blok.default_open || false);
+
+  return (
+    <div>
+      <button onClick={() => setOpen(!open)}>{blok.title}</button>
+      {open && <StoryblokBlocks blocks={blok.body} />}
+    </div>
+  );
+}
+```
+
+### Why this fails at build time
+
+Next.js performs static analysis of the import graph. When it encounters `"use client"`, it marks that file as a client module. Every `import` inside it is then also pulled into the client bundle.
+
+The import chain looks like this:
+
+```
+BrokenAccordion  ('use client')
+  └─ imports StoryblokBlocks  (from registry)
+       └─ registry imports ProductList
+            └─ ProductList imports ProductRows
+                 └─ ProductRows imports db.ts
+                      └─ db.ts has  import "server-only"
+```
+
+The `server-only` package throws a hard build error the moment it is included in a client bundle:
+
+```
+Error: You're importing a component that needs 'server-only'. That only works
+in a Server Component but one of its parents is marked with 'use client'.
+```
+
+This is not specific to Storyblok. Any time an editor adds a new blok type whose component transitively imports server-only code, a `BrokenAccordion`-style Client Component would break the build. The wrapper pattern insulates the client module from the entire server import tree.
+
+### The rule
+
+> A Client Component can **use** the output of Server Components via `children` or props, but it can **never import** a module that transitively imports server-only code.
+
+The `children` prop is the escape hatch. It carries already-resolved React elements — plain data — not the server module itself. The module boundary is never crossed.
+
+| Approach                                                         | Import graph                         | Result          |
+| ---------------------------------------------------------------- | ------------------------------------ | --------------- |
+| `BrokenAccordion` imports `StoryblokBlocks`                      | Client → server-only                 | Build error     |
+| `Accordion` (wrapper) passes `<StoryblokBlocks />` as `children` | Server renders, client receives HTML | Works correctly |
diff --git a/packages/react/src/v2/index.ts b/packages/react/src/v2/index.ts
new file mode 100644
index 000000000..1d5ae5aa5
--- /dev/null
+++ b/packages/react/src/v2/index.ts
@@ -0,0 +1,30 @@
+export interface SbBlokData {
+  _uid: string;
+  component: string;
+  _editable?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Helper type for typing blok component props.
+ * Use this instead of `{ blok: SbBlokData & { ... } }` to stay compatible
+ * with the component registry.
+ *
+ * @example
+ * type PageProps = StoryblokComponentProps<{ body: SbBlokData[] }>;
+ * export default function Page({ blok }: PageProps) { ... }
+ */
+export interface StoryblokComponentProps<T extends Record<string, unknown> = Record<string, unknown>> {
+  blok: SbBlokData & T;
+}
+
+export { createRichTextRenderer } from '../core/richtext';
+export { type ComponentEntry, createRegistry, type RegistryConfig, type RegistryResult } from './component-registry';
+
+export { StoryblokRichText } from './StoryblokRichText';
+export {
+  type ContentApiClientConfig,
+  createApiClient,
+  type Story,
+} from '@storyblok/api-client';
+export { storyblokEditable } from '@storyblok/live-preview';
diff --git a/packages/react/src/v2/rsc/StoryblokPreview.tsx b/packages/react/src/v2/rsc/StoryblokPreview.tsx
new file mode 100644
index 000000000..54a19e941
--- /dev/null
+++ b/packages/react/src/v2/rsc/StoryblokPreview.tsx
@@ -0,0 +1,168 @@
+'use client';
+import { onStoryblokEditorEvent } from '@storyblok/live-preview';
+import type { Story } from '@storyblok/api-client';
+import {
+  type ReactNode,
+  Suspense,
+  use,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+
+export interface StoryblokPreviewProps {
+  /**
+   * Server action responsible for rendering updated content.
+   */
+  renderContent: (story: Story) => Promise<ReactNode>;
+  /**
+   * Initial server-rendered content passed as children.
+   *
+   * Returned directly on first render with no state involvement, so Suspense
+   * boundaries inside the tree (e.g. WeatherWidget) stream normally.
+   *
+   * IMPORTANT: never store this in useState. Storing a ReactNode that contains
+   * async server components in useState forces the RSC serialiser to fully
+   * await every async component in the tree before it can send the initial
+   * HTML, bypassing Suspense streaming and causing a blank page for the full
+   * duration of the slowest component.
+   */
+  children: ReactNode;
+  /**
+   * Milliseconds to wait after the last editor event before triggering a
+   * re-render. Prevents a Server Action call on every individual keystroke.
+   *
+   * Defaults to 300 ms.
+   */
+  debounceMs?: number;
+}
+
+/**
+ * Inner component that calls use() inside its own Suspense boundary.
+ * Keeping it separate means use() only suspends this subtree, not the whole
+ * page. Once the promise resolves, onCommit is called so the parent can
+ * advance the Suspense fallback to the freshly rendered content.
+ */
+function LiveContent({
+  promise,
+  onCommit,
+}: {
+  promise: Promise<ReactNode>;
+  onCommit: (content: ReactNode) => void;
+}) {
+  const content = use(promise);
+
+  // After use() resolves, persist the content so subsequent editor updates
+  // show the most-recent rendered state as the fallback rather than the
+  // original SSR snapshot.
+  useEffect(() => {
+    onCommit(content);
+  }, [content, onCommit]);
+
+  return <>{content}</>;
+}
+
+export function StoryblokPreview({
+  renderContent,
+  children,
+  debounceMs = 300,
+}: StoryblokPreviewProps) {
+  // Store the Promise itself — not the resolved ReactNode.
+  //
+  // Storing ReactNode in useState forces the RSC serializer to fully await
+  // every async component in the tree before it can commit the state value,
+  // bypassing Suspense streaming and causing a full blank-page wait.
+  //
+  // Storing a Promise lets React.use() + Suspense handle async resolution
+  // progressively: the initial RSC shell (with skeleton fallbacks) can arrive
+  // quickly, and slow components stream in independently.
+  const [livePromise, setLivePromise] = useState<Promise<ReactNode> | null>(
+    null,
+  );
+
+  // Tracks the last successfully committed content from a renderContent call.
+  //
+  // Initialized to null — NOT to `children`. Storing `children` here would
+  // have the same effect as any other named prop: the RSC serialiser would
+  // need to fully await every async component in the tree (e.g. WeatherWidget
+  // with a 10 s fetch) before committing the state, blocking the initial HTML.
+  //
+  // The Suspense fallback uses `committedContent ?? children`:
+  //   • Before the first renderContent resolves: children is used directly
+  //     from the prop (stays in the RSC streaming channel — safe).
+  //   • After the first renderContent resolves: committedContent holds the
+  //     server-rendered output (fully resolved, safe to store in state).
+  //     Subsequent editor updates show the latest committed state as the
+  //     fallback instead of jumping back to the original SSR snapshot.
+  const [committedContent, setCommittedContent] = useState<ReactNode | null>(
+    null,
+  );
+
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+    let unsubscribe: (() => void) | undefined;
+
+    const setup = async () => {
+      unsubscribe = await onStoryblokEditorEvent((updatedStory) => {
+        if (!mounted) {
+          return;
+        }
+
+        if (debounceTimer.current !== null) {
+          clearTimeout(debounceTimer.current);
+        }
+
+        debounceTimer.current = setTimeout(() => {
+          debounceTimer.current = null;
+          if (!mounted) {
+            return;
+          }
+
+          // Set the promise directly — no useTransition, no awaiting here.
+          // React.use() inside LiveContent reads it; the Suspense boundary
+          // shows the fallback while the server action streams its RSC response.
+          setLivePromise(renderContent(updatedStory as Story));
+        }, debounceMs);
+      });
+    };
+
+    setup();
+
+    return () => {
+      mounted = false;
+      if (debounceTimer.current !== null) {
+        clearTimeout(debounceTimer.current);
+      }
+      unsubscribe?.();
+    };
+  }, [renderContent, debounceMs]);
+
+  // No editor update yet — return children with zero state involvement.
+  // This is the initial SSR/streaming path: Suspense boundaries inside the
+  // children tree (e.g. WeatherWidget) fire normally because nothing here
+  // interferes with them.
+  if (!livePromise) {
+    return <>{children}</>;
+  }
+
+  // Editor update in flight or resolved.
+  //
+  // Fallback precedence:
+  //   1. committedContent — output of the last resolved renderContent call.
+  //      Fully resolved server-rendered content; safe in state.
+  //   2. children — the initial SSR tree accessed directly from the prop
+  //      (never from state) so it stays in the RSC streaming channel.
+  //
+  // This means the page always shows the most-recently committed state while
+  // a new render is in flight, and never reverts to the original SSR snapshot
+  // after the first editor update has already resolved.
+  return (
+    <Suspense fallback={<>{committedContent ?? children}</>}>
+      <LiveContent promise={livePromise} onCommit={setCommittedContent} />
+    </Suspense>
+  );
+}
+
+export default StoryblokPreview;
diff --git a/packages/react/src/v2/rsc/index.ts b/packages/react/src/v2/rsc/index.ts
new file mode 100644
index 000000000..373bd9554
--- /dev/null
+++ b/packages/react/src/v2/rsc/index.ts
@@ -0,0 +1 @@
+export { default as StoryblokPreview } from './StoryblokPreview';
diff --git a/packages/react/vite.config.ts b/packages/react/vite.config.ts
index c7dec2018..ad2782ab5 100644
--- a/packages/react/vite.config.ts
+++ b/packages/react/vite.config.ts
@@ -9,7 +9,6 @@ export default defineConfig({
     react(),
     dts({
       insertTypesEntry: true,
-      rollupTypes: true,
     }),
     preserveDirectives(),
   ],
@@ -21,9 +20,13 @@ export default defineConfig({
   build: {
     lib: {
       entry: {
-        index: resolve(__dirname, 'src/index.ts'),
-        ssr: resolve(__dirname, 'src/ssr/index.ts'),
-        rsc: resolve(__dirname, 'src/rsc/index.ts'),
+        'index': resolve(__dirname, 'src/index.ts'),
+        'ssr': resolve(__dirname, 'src/ssr/index.ts'),
+        'rsc': resolve(__dirname, 'src/rsc/index.ts'),
+        // v2 experimental entries
+        'next': resolve(__dirname, 'src/v2/index.ts'),
+        'next/rsc': resolve(__dirname, 'src/v2/rsc/index.ts'),
+        'next/client': resolve(__dirname, 'src/v2/client/index.ts'),
       },
       name: 'storyblokReact',
       fileName: (format, entry) => {
@@ -46,8 +49,9 @@ export default defineConfig({
         /^next\//,
       ],
       output: {
-        preserveModules: true,
         globals: { react: 'React' },
+        preserveModules: true,
+        preserveModulesRoot: 'src',
       },
     },
   },
diff --git a/packages/region-helper/package.json b/packages/region-helper/package.json
index c728ac44a..6b30946ae 100644
--- a/packages/region-helper/package.json
+++ b/packages/region-helper/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@storyblok/region-helper",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "",
   "repository": {
     "type": "git",
diff --git a/packages/richtext/package.json b/packages/richtext/package.json
index 4af98372a..02a3f6446 100644
--- a/packages/richtext/package.json
+++ b/packages/richtext/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/richtext",
   "type": "module",
-  "version": "5.0.1",
+  "version": "5.2.0",
   "description": "Storyblok RichText Resolver",
   "author": "Storyblok",
   "license": "MIT",
diff --git a/packages/richtext/playground/vanilla/src/main.ts b/packages/richtext/playground/vanilla/src/main.ts
index c6abed9b7..f4ba95793 100644
--- a/packages/richtext/playground/vanilla/src/main.ts
+++ b/packages/richtext/playground/vanilla/src/main.ts
@@ -5,7 +5,8 @@ import type { SbRichTextRenderContext } from '@storyblok/richtext';
 import test from '/test.md?url&raw';
 import testHTML from '/test.html?url&raw';
 
-const richtextFromMarkdown = markdownToStoryblokRichtext(test, /*  {
+const richtextFromMarkdown = markdownToStoryblokRichtext(
+  test /*  {
   resolvers: {
     [MarkdownTokenTypes.PARAGRAPH]: (_token, children) => {
       return {
@@ -15,16 +16,12 @@ const richtextFromMarkdown = markdownToStoryblokRichtext(test, /*  {
       };
     },
   },
-} */);
+} */,
+);
 
 const richtextFromHTML = htmlToStoryblokRichtext(testHTML);
 
 const options: SbRichTextRenderContext = {
-  // resolvers: {
-  //   [BlockTypes.HEADING]: (node: StoryblokRichTextNode<string>, ctx) => {
-  //     return ctx.originalResolvers.get(BlockTypes.HEADING)?.(node, ctx) || '';
-  //   },
-  // },
   // optimizeImages: {
   //   class: 'v-class',
   //   loading: 'lazy',
diff --git a/packages/richtext/src/render-richtext.test.ts b/packages/richtext/src/render-richtext.test.ts
index 2a4e65457..714824c64 100644
--- a/packages/richtext/src/render-richtext.test.ts
+++ b/packages/richtext/src/render-richtext.test.ts
@@ -107,6 +107,35 @@ describe('renderRichText', () => {
       const html = renderRichText(table.input, options);
       expect(html).toBe(table.expected);
     });
+    const text_node = customRendererFixture.text_node;
+    it(text_node.title, () => {
+      const options: SbRichTextRenderContext = {
+        data: { prefix: '[prefix]' },
+        renderers: {
+          text: ({ text: content, context }) => {
+            const data = context?.data as { prefix: string };
+            return `${data.prefix} ${content.toUpperCase()}`;
+          },
+        },
+      };
+      const html = renderRichText(text_node.input, options);
+      expect(html).toBe(text_node.expected);
+    });
+    const infinite_loop = customRendererFixture.infinite_loop_prevention;
+    it(infinite_loop.title, () => {
+      const options: SbRichTextRenderContext = {
+        renderers: {
+          heading: ({ attrs, content, context }) => {
+            // Simulate what a real component would do: call renderRichText internally
+            // Without loop prevention, this would cause infinite recursion
+            const inner = renderRichText(content, context);
+            return `<h${attrs?.level} data-type="recursive-heading" data-level="${attrs?.level}">${inner}</h${attrs?.level}>`;
+          },
+        },
+      };
+      const html = renderRichText(infinite_loop.input, options);
+      expect(html).toBe(infinite_loop.expected);
+    });
   });
   describe('blok nodes', () => {
     const blokDoc: SbRichTextDoc = {
@@ -198,4 +227,101 @@ describe('renderRichText', () => {
       expect(renderRichText(node)).toContain('href="javascript:alert(&quot;xss&quot;)"');
     });
   });
+
+  describe('context data', () => {
+    it('passes data to custom node renderers', () => {
+      const doc: SbRichTextDoc = {
+        type: 'doc',
+        content: [{ type: 'heading', attrs: { level: 1 }, content: [text('Title')] }],
+      };
+      const options: SbRichTextRenderContext = {
+        data: { theme: 'dark', prefix: 'custom' },
+        renderers: {
+          heading: ({ attrs, children, context }) => {
+            const data = context?.data as { theme: string; prefix: string };
+            return `<h${attrs?.level} class="${data.theme}" data-prefix="${data.prefix}">${children}</h${attrs?.level}>`;
+          },
+        },
+      };
+      expect(renderRichText(doc, options)).toBe('<h1 class="dark" data-prefix="custom">Title</h1>');
+    });
+
+    it('passes data to custom mark renderers', () => {
+      const doc: SbRichTextDoc = {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [text('Bold text', [{ type: 'bold' }])] }],
+      };
+      const options: SbRichTextRenderContext = {
+        data: { className: 'highlight' },
+        renderers: {
+          bold: ({ children, context }) => {
+            const data = context?.data as { className: string };
+            return `<strong class="${data.className}">${children}</strong>`;
+          },
+        },
+      };
+      expect(renderRichText(doc, options)).toBe('<p><strong class="highlight">Bold text</strong></p>');
+    });
+
+    it('passes data to custom link renderers', () => {
+      const doc: SbRichTextDoc = {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [text('Click here', [linkMark('https://example.com')])] }],
+      };
+      const options: SbRichTextRenderContext = {
+        data: { trackingId: 'abc123' },
+        renderers: {
+          link: ({ attrs, children, context }) => {
+            const data = context?.data as { trackingId: string };
+            return `<a href="${attrs?.href}" data-tracking="${data.trackingId}">${children}</a>`;
+          },
+        },
+      };
+      expect(renderRichText(doc, options)).toBe('<p><a href="https://example.com" data-tracking="abc123">Click here</a></p>');
+    });
+
+    it('allows custom text node renderer', () => {
+      const doc: SbRichTextDoc = {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [text('hello world')] }],
+      };
+      const options: SbRichTextRenderContext = {
+        renderers: {
+          text: ({ text: content }) => content.toUpperCase(),
+        },
+      };
+      expect(renderRichText(doc, options)).toBe('<p>HELLO WORLD</p>');
+    });
+
+    it('custom text renderer receives context with data', () => {
+      const doc: SbRichTextDoc = {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [text('hello')] }],
+      };
+      const options: SbRichTextRenderContext = {
+        data: { wrap: '**' },
+        renderers: {
+          text: ({ text: content, context }) => {
+            const data = context?.data as { wrap: string };
+            return `${data.wrap}${content}${data.wrap}`;
+          },
+        },
+      };
+      expect(renderRichText(doc, options)).toBe('<p>**hello**</p>');
+    });
+
+    it('custom text renderer with marks still applies marks', () => {
+      const doc: SbRichTextDoc = {
+        type: 'doc',
+        content: [{ type: 'paragraph', content: [text('hello', [{ type: 'bold' }])] }],
+      };
+      const options: SbRichTextRenderContext = {
+        renderers: {
+          text: ({ text: content }) => content.toUpperCase(),
+        },
+      };
+      // Custom text renderer takes full control, marks are not applied
+      expect(renderRichText(doc, options)).toBe('<p>HELLO</p>');
+    });
+  });
 });
diff --git a/packages/richtext/src/render-richtext.ts b/packages/richtext/src/render-richtext.ts
index 1947fac18..e35c3e13d 100644
--- a/packages/richtext/src/render-richtext.ts
+++ b/packages/richtext/src/render-richtext.ts
@@ -26,18 +26,25 @@ export function renderRichText(
   return nodes?.length ? renderChildren(nodes, context) : '';
 }
 type NodeRenderer = (props: SbRichTextNode & { children: string; context?: SbRichTextRenderContext }) => string;
-type MarkRenderer = (props: SbRichTextMark & { children: string }) => string;
+type MarkRenderer = (props: SbRichTextMark & { children: string; context?: SbRichTextRenderContext }) => string;
 
 /** Renders a single node to HTML. */
 function renderNode(node: SbRichTextNode, context?: SbRichTextRenderContext): string {
-  if (node.type === 'text') {
-    return renderTextNode(node, node.marks, context);
-  }
-  const content = node.content ? renderChildren(node.content, context) : '';
+  const content = node.type !== 'text' && node.content ? renderChildren(node.content, context) : '';
+
   // Custom renderer takes full control
   const customRenderer = context?.renderers?.[node.type] as NodeRenderer | undefined;
   if (customRenderer) {
-    return customRenderer({ ...node, children: content, context });
+    // When passing context to a custom renderer, exclude that renderer type
+    // to prevent infinite loops if the custom renderer calls renderRichText internally
+    const contextForCustom = context?.renderers?.[node.type]
+      ? { ...context, renderers: { ...context.renderers, [node.type]: undefined } }
+      : context;
+    return customRenderer({ ...node, children: content, context: contextForCustom });
+  }
+
+  if (node.type === 'text') {
+    return renderTextNode(node, node.marks, context);
   }
 
   if (node.type === 'blok') {
@@ -167,6 +174,7 @@ function wrapWithMark(
     return customRenderer({
       ...mark,
       children: content,
+      context,
     });
   }
 
@@ -202,6 +210,7 @@ function renderLinkGroup(
     return customRenderer({
       ...linkMark,
       children: inner,
+      context,
     });
   }
 
diff --git a/packages/richtext/src/static/generate/richtext-type.ts b/packages/richtext/src/static/generate/richtext-type.ts
index 2fcf8e130..c5f90974f 100644
--- a/packages/richtext/src/static/generate/richtext-type.ts
+++ b/packages/richtext/src/static/generate/richtext-type.ts
@@ -1,7 +1,10 @@
 import type { AnyExtension } from '@tiptap/core';
 import { getSchema } from '@tiptap/core';
 import type { MarkType, NodeType, Schema } from 'prosemirror-model';
-import { allAttrKeys, type ExtensionAttrMap } from '../../extensions/richtext-attrs';
+import {
+  allAttrKeys,
+  type ExtensionAttrMap,
+} from '../../extensions/richtext-attrs';
 import { getStoryblokTiptapExtensions } from '../../extensions';
 
 const attrKeySet = new Set<keyof ExtensionAttrMap>(allAttrKeys);
@@ -50,7 +53,7 @@ function nodeShape(schema: Schema, name: string): string {
 }
 
 function markShape(name: string): string {
-  return `{ type: '${name}'; attrs?: TiptapMarkAttributes['${name}']; _key?: string; }`;
+  return `{ type: '${name}'; attrs?: TiptapMarkAttributes['${name}']; _key?: string; context?: TContext; }`;
 }
 
 /** Generate SbRichTextNode discriminated union type */
@@ -63,7 +66,7 @@ function genPMNode(schema: Schema): string {
 }
 
 function genPMMark(schema: Schema): string {
-  let out = 'export type SbRichTextMark =\n';
+  let out = 'export type SbRichTextMark<TContext = unknown> =\n';
   for (const [name] of Object.entries(schema.marks)) {
     out += `  | ${markShape(name)}\n`;
   }
@@ -78,8 +81,10 @@ function genPMMark(schema: Schema): string {
  */
 function genElementByType(schema: Schema): string {
   let out = '/**\n * Flat lookup of element shapes keyed by `type`.\n';
-  out += ' * Prefer this over `Extract<SbRichTextNode, { type: T }>` in places\n';
-  out += ' * that need to be resolved by limited type resolvers (e.g. Vue SFC macros).\n */\n';
+  out
+    += ' * Prefer this over `Extract<SbRichTextNode, { type: T }>` in places\n';
+  out
+    += ' * that need to be resolved by limited type resolvers (e.g. Vue SFC macros).\n */\n';
   out += 'export interface SbRichTextElementByType<TContext = unknown> {\n';
   for (const [name] of Object.entries(schema.nodes) as [string, NodeType][]) {
     out += `  ${name}: ${nodeShape(schema, name)};\n`;
diff --git a/packages/richtext/src/static/types.ts b/packages/richtext/src/static/types.ts
index d73a5aeaa..dfa08f745 100644
--- a/packages/richtext/src/static/types.ts
+++ b/packages/richtext/src/static/types.ts
@@ -1,7 +1,7 @@
 import type { SbRichTextImageOptions } from '../types';
 import type { SbRichTextElementByType, SbRichTextNode, TiptapMarkName, TiptapNodeName } from './types.generated';
 
-export type SbRichTextElement = Exclude<TiptapNodeName | TiptapMarkName, 'text'>;
+export type SbRichTextElement = TiptapNodeName | TiptapMarkName;
 
 interface ISbComponentType<T extends string> {
   _uid?: string;
@@ -46,6 +46,7 @@ export type SbRichTextRendererMap = {
 export interface SbRichTextRenderContext {
   renderers?: SbRichTextRendererMap;
   optimizeImage?: boolean | Partial<SbRichTextImageOptions>;
+  data?: unknown;
 }
 
 export { SbRichTextImageOptions };
diff --git a/packages/richtext/src/test-utils/integration.ts b/packages/richtext/src/test-utils/integration.ts
index 672c121b3..0d131a919 100644
--- a/packages/richtext/src/test-utils/integration.ts
+++ b/packages/richtext/src/test-utils/integration.ts
@@ -1,4 +1,11 @@
-import { linkMark, table, tableCell, tableHeader, tableRow, text } from './helpers';
+import {
+  linkMark,
+  table,
+  tableCell,
+  tableHeader,
+  tableRow,
+  text,
+} from './helpers';
 import type { HtmlFixture } from './types';
 
 export const integrationFixtures: HtmlFixture[] = [
@@ -7,9 +14,13 @@ export const integrationFixtures: HtmlFixture[] = [
     input: {
       type: 'paragraph',
       attrs: { textAlign: 'center' },
-      content: [text('Centered text with ', [linkMark('/url')]), text('link', [linkMark('/url')])],
+      content: [
+        text('Centered text with ', [linkMark('/url')]),
+        text('link', [linkMark('/url')]),
+      ],
     },
-    expected: '<p style="text-align: center;"><a href="/url">Centered text with link</a></p>',
+    expected:
+      '<p style="text-align: center;"><a href="/url">Centered text with link</a></p>',
   },
   {
     title: 'renders empty paragraph with alignment',
@@ -23,16 +34,58 @@ export const integrationFixtures: HtmlFixture[] = [
   {
     title: 'kitchen sink document',
     input: [
-      { type: 'heading', attrs: { level: 4, textAlign: 'right' }, content: [text('Feature Heading', [{ type: 'highlight', attrs: { color: 'rgb(204, 255, 204)' } }, linkMark('/feature', { target: '_blank' })])] },
-      { type: 'paragraph', attrs: { textAlign: 'center' }, content: [text('Intro', [{ type: 'bold' }, { type: 'styled', attrs: { class: 'lead' } }])] },
-      { type: 'image', attrs: { id: 44, src: 'https://foo', alt: 'center', title: 'T', source: 'Z', copyright: null, meta_data: null } },
-      { type: 'bullet_list', content: [{ type: 'list_item', content: [{ type: 'paragraph', content: [text('B')] }] }] },
+      {
+        type: 'heading',
+        attrs: { level: 4, textAlign: 'right' },
+        content: [
+          text('Feature Heading', [
+            { type: 'highlight', attrs: { color: 'rgb(204, 255, 204)' } },
+            linkMark('/feature', { target: '_blank' }),
+          ]),
+        ],
+      },
+      {
+        type: 'paragraph',
+        attrs: { textAlign: 'center' },
+        content: [
+          text('Intro', [
+            { type: 'bold' },
+            { type: 'styled', attrs: { class: 'lead' } },
+          ]),
+        ],
+      },
+      {
+        type: 'image',
+        attrs: {
+          id: 44,
+          src: 'https://foo',
+          alt: 'center',
+          title: 'T',
+          source: 'Z',
+          copyright: null,
+          meta_data: null,
+        },
+      },
+      {
+        type: 'bullet_list',
+        content: [
+          {
+            type: 'list_item',
+            content: [{ type: 'paragraph', content: [text('B')] }],
+          },
+        ],
+      },
     ],
-    expected: '<h4 style="text-align: right;"><a href="/feature" target="_blank"><mark style="background-color: rgb(204, 255, 204);">Feature Heading</mark></a></h4><p style="text-align: center;"><span class="lead"><strong>Intro</strong></span></p><img id="44" src="https://foo" alt="center" title="T"><ul><li><p>B</p></li></ul>',
+    expected:
+      '<h4 style="text-align: right;"><a href="/feature" target="_blank"><mark style="background-color: rgb(204, 255, 204);">Feature Heading</mark></a></h4><p style="text-align: center;"><span class="lead"><strong>Intro</strong></span></p><img id="44" src="https://foo" alt="center" title="T"><ul><li><p>B</p></li></ul>',
   },
 ];
 
-const testLinkMark = linkMark('/richtext', { linktype: 'story', target: '_self', custom: { rel: 'noopener', title: 'Navigate to richtext page' } });
+const testLinkMark = linkMark('/richtext', {
+  linktype: 'story',
+  target: '_self',
+  custom: { rel: 'noopener', title: 'Navigate to richtext page' },
+});
 export const customRendererFixture: Record<string, HtmlFixture> = {
   node_and_mark: {
     title: 'renders custom node and mark overrides',
@@ -61,55 +114,112 @@ export const customRendererFixture: Record<string, HtmlFixture> = {
             text('This is a '),
             text('bold text', [{ type: 'bold' }]),
             text(' with a '),
-            text('blue color', [{
-              type: 'textStyle',
-              attrs: {
-                color: 'rgb(27, 74, 230)',
+            text('blue color', [
+              {
+                type: 'textStyle',
+                attrs: {
+                  color: 'rgb(27, 74, 230)',
+                },
               },
-            }]),
+            ]),
             text(' and a link to '),
             text('some ', [testLinkMark]),
             text('Italic', [testLinkMark, { type: 'italic' }]),
             text(' link', [testLinkMark]),
             text('.'),
-
           ],
         },
       ],
     },
-    expected: '<h2 data-type="custom-heading" data-level="2">Custom Rich Text Test</h2><p>This is a <b data-type="custom-bold">bold text</b> with a <span style="color: rgb(27, 74, 230);">blue color</span> and a link to <a data-type="custom-link" href="/richtext" target="_self" rel="noopener" title="Navigate to richtext page">some <em>Italic</em> link</a>.</p>',
+    expected:
+      '<h2 data-type="custom-heading" data-level="2">Custom Rich Text Test</h2><p>This is a <b data-type="custom-bold">bold text</b> with a <span style="color: rgb(27, 74, 230);">blue color</span> and a link to <a data-type="custom-link" href="/richtext" target="_self" rel="noopener" title="Navigate to richtext page">some <em>Italic</em> link</a>.</p>',
   },
-  recursive:
-  {
-    title: 'renders custom node overrides with recursive StoryblokRichText or renderRichtext in custom renderers',
-    input: [{
-      type: 'heading',
-      attrs: { level: 1, textAlign: null },
-      content: [text('Title', [{ type: 'bold' }])],
-    }, {
-      type: 'paragraph',
-      attrs: { textAlign: 'center' },
-      content: [text('Hello Storyblok', [{ type: 'bold' }])],
-    }],
-    expected: '<h1 data-type="custom-heading" data-level="1"><b data-type="custom-bold">Title</b></h1><p style="text-align: center;"><b data-type="custom-bold">Hello Storyblok</b></p>',
+  recursive: {
+    title:
+      'renders custom node overrides with recursive StoryblokRichText or renderRichtext in custom renderers',
+    input: [
+      {
+        type: 'heading',
+        attrs: { level: 1, textAlign: null },
+        content: [text('Title', [{ type: 'bold' }])],
+      },
+      {
+        type: 'paragraph',
+        attrs: { textAlign: 'center' },
+        content: [text('Hello Storyblok', [{ type: 'bold' }])],
+      },
+    ],
+    expected:
+      '<h1 data-type="custom-heading" data-level="1"><b data-type="custom-bold">Title</b></h1><p style="text-align: center;"><b data-type="custom-bold">Hello Storyblok</b></p>',
   },
-  code_block:
-  {
+  code_block: {
     title: 'allows custom code_block renderer to control attribute placement',
     input: {
       type: 'code_block',
       attrs: { class: 'typescript' },
       content: [text('const x: number = 1;')],
     },
-    expected: '<pre class="language-typescript"><code data-lang="typescript">const x: number = 1;</code></pre>',
+    expected:
+      '<pre class="language-typescript"><code data-lang="typescript">const x: number = 1;</code></pre>',
   },
-  table:
-  {
+  table: {
     title: 'allows custom table renderer',
     input: table([
-      tableRow([tableHeader('Name'), tableHeader('Age'), tableHeader('Location')]),
-      tableRow([tableCell('John', { colspan: 2 }, [{ type: 'bold' }]), tableCell('25'), tableCell('New York')]),
+      tableRow([
+        tableHeader('Name'),
+        tableHeader('Age'),
+        tableHeader('Location'),
+      ]),
+      tableRow([
+        tableCell('John', { colspan: 2 }, [{ type: 'bold' }]),
+        tableCell('25'),
+        tableCell('New York'),
+      ]),
     ]),
-    expected: '<table class="custom-table"><thead><tr><th><p>Name</p></th><th><p>Age</p></th><th><p>Location</p></th></tr></thead><tbody><tr><td colspan="2"><p><b data-type="custom-bold">John</b></p></td><td><p>25</p></td><td><p>New York</p></td></tr></tbody></table>',
+    expected:
+      '<table class="custom-table"><thead><tr><th><p>Name</p></th><th><p>Age</p></th><th><p>Location</p></th></tr></thead><tbody><tr><td colspan="2"><p><b data-type="custom-bold">John</b></p></td><td><p>25</p></td><td><p>New York</p></td></tr></tbody></table>',
+  },
+  text_node: {
+    title: 'allows custom text node renderer with context data',
+    input: {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          attrs: { textAlign: null },
+          content: [text('Hello '), text('World')],
+        },
+        {
+          type: 'heading',
+          attrs: { level: 1, textAlign: null },
+          content: [text('Title')],
+        },
+      ],
+    },
+    expected: '<p>[prefix] HELLO [prefix] WORLD</p><h1>[prefix] TITLE</h1>',
+  },
+  infinite_loop_prevention: {
+    title:
+      'prevents infinite loop when custom renderer calls renderRichText/StoryblokRichText internally',
+    input: {
+      type: 'doc',
+      content: [
+        {
+          type: 'heading',
+          attrs: { level: 1, textAlign: null },
+          content: [text('Outer'), text(' Heading', [{ type: 'bold' }])],
+        },
+        {
+          type: 'paragraph',
+          content: [text('Normal paragraph')],
+        },
+      ],
+    },
+    // The custom heading renderer calls renderRichText internally for its children.
+    // Without loop prevention, it would infinitely recurse on headings.
+    // With protection, the heading renderer is removed from context when rendering children,
+    // so nested headings render with default behavior.
+    expected:
+      '<h1 data-type="recursive-heading" data-level="1">Outer<strong> Heading</strong></h1><p>Normal paragraph</p>',
   },
 };
diff --git a/packages/svelte/package.json b/packages/svelte/package.json
index cbcbe9f14..e4bc66b66 100644
--- a/packages/svelte/package.json
+++ b/packages/svelte/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/svelte",
   "type": "module",
-  "version": "7.0.1",
+  "version": "7.2.0",
   "private": false,
   "description": "SDK to integrate Storyblok into your project using Svelte.",
   "author": "Storyblok",
diff --git a/packages/svelte/src/lib/StoryblokRichText.svelte b/packages/svelte/src/lib/StoryblokRichText.svelte
index 27ccd0b7f..29f767d1f 100644
--- a/packages/svelte/src/lib/StoryblokRichText.svelte
+++ b/packages/svelte/src/lib/StoryblokRichText.svelte
@@ -7,8 +7,8 @@
     document: SbRichTextInput;
   } & Record<string, unknown>;
 
-  const { document, components = {}, optimizeImage }: Props = $props();
+  const { document, components = {}, optimizeImage, data }: Props = $props();
   const nodes = $derived.by(() => normalizeNodes(document, true));
 </script>
 
-<RenderChildren {nodes} options={{ components, optimizeImage }} />
+<RenderChildren {nodes} options={{ components, optimizeImage, data }} />
diff --git a/packages/svelte/src/lib/richtext-helpers.ts b/packages/svelte/src/lib/richtext-helpers.ts
index 5bd57d2d5..1111e6657 100644
--- a/packages/svelte/src/lib/richtext-helpers.ts
+++ b/packages/svelte/src/lib/richtext-helpers.ts
@@ -4,6 +4,7 @@ import type { Component, Snippet } from 'svelte';
 export interface SbSvelteRichTextRenderContext {
   optimizeImage?: boolean | SbRichTextImageOptions;
   components?: SbSvelteRichTextComponentMap;
+  data?: unknown;
 }
 
 type AnyComponent = Component<any>;
diff --git a/packages/svelte/src/lib/richtext/RenderLinkGroup.svelte b/packages/svelte/src/lib/richtext/RenderLinkGroup.svelte
index f685261e1..a04f62dc4 100644
--- a/packages/svelte/src/lib/richtext/RenderLinkGroup.svelte
+++ b/packages/svelte/src/lib/richtext/RenderLinkGroup.svelte
@@ -16,7 +16,7 @@
 </script>
 
 {#if CustomComponent}
-  <CustomComponent {...linkMark}>
+  <CustomComponent {...linkMark} context={options}>
     <RenderLinkInner {nodes} {options} />
   </CustomComponent>
 {:else}
diff --git a/packages/svelte/src/lib/richtext/RenderNode.svelte b/packages/svelte/src/lib/richtext/RenderNode.svelte
index 8ebf55cbc..50c372d05 100644
--- a/packages/svelte/src/lib/richtext/RenderNode.svelte
+++ b/packages/svelte/src/lib/richtext/RenderNode.svelte
@@ -16,18 +16,26 @@
 
   const { node, options }: Props = $props();
   const CustomComponent = $derived(
-    options.components && node.type !== 'text' ? options.components[node.type] : undefined,
+    options.components ? options.components[node.type] : undefined,
+  );
+
+  // When passing context to a custom component, exclude that component type
+  // to prevent infinite loops if the custom component uses StoryblokRichText internally
+  const contextForCustom = $derived(
+    CustomComponent
+      ? { ...options, components: { ...options.components, [node.type]: undefined } }
+      : options,
   );
 </script>
 
-{#if node.type === 'text'}
-  <RenderTextNodeWithMarks {node} marks={node.marks} {options} />
-{:else if CustomComponent}
-  <CustomComponent {...node} context={options}>
-    {#if node.content}
+{#if CustomComponent}
+  <CustomComponent {...node} context={contextForCustom}>
+    {#if node.type !== 'text' && node.content}
       <RenderChildren nodes={node.content} {options} />
     {/if}
   </CustomComponent>
+{:else if node.type === 'text'}
+  <RenderTextNodeWithMarks {node} marks={node.marks} {options} />
 {:else if node.type === 'image'}
   <RenderImage {node} {options} />
 {:else if node.type === 'blok'}
diff --git a/packages/svelte/src/lib/richtext/RenderTextNodeWithMarks.svelte b/packages/svelte/src/lib/richtext/RenderTextNodeWithMarks.svelte
index da4f13f7c..46c39d758 100644
--- a/packages/svelte/src/lib/richtext/RenderTextNodeWithMarks.svelte
+++ b/packages/svelte/src/lib/richtext/RenderTextNodeWithMarks.svelte
@@ -24,7 +24,7 @@
 {#if reversedMarks.length === 0}
   {node.text}
 {:else if MarkComponent}
-  <MarkComponent {...mark}>
+  <MarkComponent {...mark} context={options}>
     <RenderTextNodeWithMarks {node} marks={rest} {options} />
   </MarkComponent>
 {:else}
diff --git a/packages/svelte/src/tests/richtext.spec.ts b/packages/svelte/src/tests/richtext.spec.ts
index ded56a40b..78fdf77be 100644
--- a/packages/svelte/src/tests/richtext.spec.ts
+++ b/packages/svelte/src/tests/richtext.spec.ts
@@ -7,6 +7,8 @@ import Bold from './richtext/Bold.svelte';
 import CustomCode from './richtext/CustomCode.svelte';
 import Heading from './richtext/Heading.svelte';
 import CustomLink from './richtext/CustomLink.svelte';
+import CustomText from './richtext/CustomText.svelte';
+import HeadingWithRichText from './richtext/HeadingWithRichText.svelte';
 
 // Helper function to clean up the HTML output for easier comparison
 export function cleanHtml(html: string) {
@@ -175,5 +177,36 @@ describe('storyblok Richtext', () => {
       expect(result).toBe(table.expected);
       unmount(component);
     });
+    const text_node = customRendererFixture.text_node;
+    it(text_node.title, () => {
+      const target = document.createElement('div');
+      const component = mount(StoryblokRichText, {
+        target,
+        props: {
+          document: text_node.input,
+          data: { prefix: '[prefix]' },
+          components: { text: CustomText },
+        },
+      });
+      flushSync();
+      const result = cleanHtml(target.innerHTML);
+      expect(result).toBe(text_node.expected);
+      unmount(component);
+    });
+    const infinite_loop = customRendererFixture.infinite_loop_prevention;
+    it(infinite_loop.title, () => {
+      const target = document.createElement('div');
+      const component = mount(StoryblokRichText, {
+        target,
+        props: {
+          document: infinite_loop.input,
+          components: { heading: HeadingWithRichText },
+        },
+      });
+      flushSync();
+      const result = cleanHtml(target.innerHTML);
+      expect(result).toBe(infinite_loop.expected);
+      unmount(component);
+    });
   });
 });
diff --git a/packages/svelte/src/tests/richtext/CustomText.svelte b/packages/svelte/src/tests/richtext/CustomText.svelte
new file mode 100644
index 000000000..eb9c7c429
--- /dev/null
+++ b/packages/svelte/src/tests/richtext/CustomText.svelte
@@ -0,0 +1,9 @@
+<script lang="ts">
+  import type { SbSvelteRichTextProps } from '$lib/richtext-helpers';
+
+  const props: SbSvelteRichTextProps<'text'> = $props();
+  const data = props.context?.data as { prefix: string } | undefined;
+  const prefix = data?.prefix ?? '';
+</script>
+
+{prefix} {props.text.toUpperCase()}
diff --git a/packages/svelte/src/tests/richtext/HeadingWithRichText.svelte b/packages/svelte/src/tests/richtext/HeadingWithRichText.svelte
new file mode 100644
index 000000000..0f128f5e9
--- /dev/null
+++ b/packages/svelte/src/tests/richtext/HeadingWithRichText.svelte
@@ -0,0 +1,18 @@
+<!--
+Custom heading component that internally uses StoryblokRichText.
+This tests the infinite loop prevention - without it, this would cause:
+HeadingWithRichText -> StoryblokRichText -> HeadingWithRichText -> ...
+-->
+<script lang="ts">
+  import type { SbSvelteRichTextProps } from '$lib/richtext-helpers';
+  import StoryblokRichText from '$lib/StoryblokRichText.svelte';
+
+  const props: SbSvelteRichTextProps<'heading'> = $props();
+  const level = props.attrs?.level || 1;
+</script>
+
+<svelte:element this={`h${level}`} data-type="recursive-heading" data-level={props.attrs?.level}>
+  {#if props.content}
+    <StoryblokRichText document={props.content} {...props.context} />
+  {/if}
+</svelte:element>
diff --git a/packages/vue/package.json b/packages/vue/package.json
index 1a142f138..68a790e54 100644
--- a/packages/vue/package.json
+++ b/packages/vue/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@storyblok/vue",
   "type": "module",
-  "version": "11.0.1",
+  "version": "11.2.0",
   "description": "SDK to integrate Storyblok into your project using Vue.",
   "author": "Storyblok",
   "license": "MIT",
diff --git a/packages/vue/src/__tests__/StoryblokRichText.test.ts b/packages/vue/src/__tests__/StoryblokRichText.test.ts
index 066cccbd3..00f3210c7 100644
--- a/packages/vue/src/__tests__/StoryblokRichText.test.ts
+++ b/packages/vue/src/__tests__/StoryblokRichText.test.ts
@@ -7,6 +7,8 @@ import CustomBold from './richtext/CustomBold.vue';
 import CustomLink from './richtext/CustomLink.vue';
 import CustomCodeBlock from './richtext/CustomCodeBlock.vue';
 import CustomTable from './richtext/CustomTable.vue';
+import CustomText from './richtext/CustomText.vue';
+import HeadingWithRichText from './richtext/HeadingWithRichText.vue';
 import { h } from 'vue';
 
 describe('storyblok vue richtext rendering', () => {
@@ -163,5 +165,32 @@ describe('storyblok vue richtext rendering', () => {
       });
       expect((wrapper.html({ raw: true }))).toBe(table.expected);
     });
+    const text_node = customRendererFixture.text_node;
+    it(text_node.title, () => {
+      const components: SbVueRichTextComponentMap = {
+        text: CustomText,
+      };
+      const wrapper = mount(StoryblokRichText, {
+        props: {
+          document: text_node.input,
+          components,
+          data: { prefix: '[prefix]' },
+        },
+      });
+      expect((wrapper.html({ raw: true }))).toBe(text_node.expected);
+    });
+    const infinite_loop = customRendererFixture.infinite_loop_prevention;
+    it(infinite_loop.title, () => {
+      const components: SbVueRichTextComponentMap = {
+        heading: HeadingWithRichText,
+      };
+      const wrapper = mount(StoryblokRichText, {
+        props: {
+          document: infinite_loop.input,
+          components,
+        },
+      });
+      expect((wrapper.html({ raw: true }))).toBe(infinite_loop.expected);
+    });
   });
 });
diff --git a/packages/vue/src/__tests__/richtext/CustomBold.vue b/packages/vue/src/__tests__/richtext/CustomBold.vue
index 7e3b92dd8..a1dc5ec02 100644
--- a/packages/vue/src/__tests__/richtext/CustomBold.vue
+++ b/packages/vue/src/__tests__/richtext/CustomBold.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { SbVueRichTextProps } from '../../index.ts';
 
+defineOptions({ inheritAttrs: false });
 defineProps<SbVueRichTextProps['bold']>();
 </script>
 
diff --git a/packages/vue/src/__tests__/richtext/CustomLink.vue b/packages/vue/src/__tests__/richtext/CustomLink.vue
index be6dd6eac..1fba3cbc2 100644
--- a/packages/vue/src/__tests__/richtext/CustomLink.vue
+++ b/packages/vue/src/__tests__/richtext/CustomLink.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import type { SbVueRichTextProps } from '../../index.ts';
 
+defineOptions({ inheritAttrs: false });
 const props = defineProps<SbVueRichTextProps['link']>();
 </script>
 
diff --git a/packages/vue/src/__tests__/richtext/CustomText.vue b/packages/vue/src/__tests__/richtext/CustomText.vue
new file mode 100644
index 000000000..99cd0a88e
--- /dev/null
+++ b/packages/vue/src/__tests__/richtext/CustomText.vue
@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import type { SbVueRichTextProps } from '../../index.ts';
+
+const props = defineProps<SbVueRichTextProps['text']>();
+const data = props.context?.data as { prefix: string } | undefined;
+const prefix = data?.prefix ?? '';
+</script>
+
+<template>
+  {{ prefix }} {{ text.toUpperCase() }}
+</template>
diff --git a/packages/vue/src/__tests__/richtext/HeadingWithRichText.vue b/packages/vue/src/__tests__/richtext/HeadingWithRichText.vue
new file mode 100644
index 000000000..b8e411a4b
--- /dev/null
+++ b/packages/vue/src/__tests__/richtext/HeadingWithRichText.vue
@@ -0,0 +1,18 @@
+<!--
+Custom heading component that internally uses StoryblokRichText.
+This tests the infinite loop prevention - without it, this would cause:
+HeadingWithRichText -> StoryblokRichText -> HeadingWithRichText -> ...
+-->
+<script setup lang="ts">
+import type { SbVueRichTextProps } from '../../index.ts';
+import StoryblokRichText from '../../components/StoryblokRichText.vue';
+
+const props = defineProps<SbVueRichTextProps['heading']>();
+const level = props.attrs?.level || 1;
+</script>
+
+<template>
+  <component :is="`h${level}`" data-type="recursive-heading" :data-level="attrs?.level">
+    <StoryblokRichText v-if="content" :document="content" v-bind="context" />
+  </component>
+</template>
diff --git a/packages/vue/src/components/StoryblokRichText.vue b/packages/vue/src/components/StoryblokRichText.vue
index 43e8a8a45..156b86b20 100644
--- a/packages/vue/src/components/StoryblokRichText.vue
+++ b/packages/vue/src/components/StoryblokRichText.vue
@@ -20,6 +20,10 @@ export default defineComponent({
       type: Object as PropType<SbVueRichTextComponentMap>,
       required: false,
     },
+    data: {
+      type: null as unknown as PropType<unknown>,
+      required: false,
+    },
   },
 
   setup(props) {
@@ -29,6 +33,7 @@ export default defineComponent({
         blok: BlokRenderer,
         ...props.components,
       },
+      data: props.data,
     });
     return () => render(props.document);
   },
diff --git a/packages/vue/src/rich-text-renderer.ts b/packages/vue/src/rich-text-renderer.ts
index 891c99cd2..a1366df8c 100644
--- a/packages/vue/src/rich-text-renderer.ts
+++ b/packages/vue/src/rich-text-renderer.ts
@@ -38,6 +38,7 @@ function resolveComponentOverride<K extends SbRichTextElement>(
 export interface SbVueRichTextRenderContext {
   optimizeImage?: boolean | Partial<SbRichTextImageOptions>;
   components?: SbVueRichTextComponentMap;
+  data?: unknown;
 }
 
 /**
@@ -98,7 +99,7 @@ function renderLinkGroup(
   });
   const Custom = resolveComponentOverride(linkMark.type, options.components);
   if (Custom) {
-    return h(Custom, { key, ...linkMark }, {
+    return h(Custom, { key, ...linkMark, context: options }, {
       default: () => inner,
     });
   }
@@ -112,19 +113,28 @@ function renderLinkGroup(
 }
 
 function renderNode(node: SbRichTextNode, options: SbVueRichTextRenderContext, key: number | string): VNode {
-  if (node.type === 'text') {
-    return renderTextNode(node as SbRichTextTextNode, options, key);
-  }
+  const content = node.type !== 'text' && node.content ? renderChildren(node.content, options) : [];
 
+  // Custom renderer takes full control
   const Custom = resolveComponentOverride(node.type, options.components);
 
   if (Custom) {
-    return h(Custom, { key, ...node, context: options }, node.content
+    // When passing context to a custom component, exclude that component type
+    // to prevent infinite loops if the custom component uses StoryblokRichText internally
+    const contextForCustom = options.components?.[node.type]
+      ? { ...options, components: { ...options.components, [node.type]: undefined } }
+      : options;
+    return h(Custom, { key, ...node, context: contextForCustom }, content.length
       ? {
-          default: () => renderChildren(node.content!, options),
+          default: () => content,
         }
       : undefined);
   }
+
+  if (node.type === 'text') {
+    return renderTextNode(node as SbRichTextTextNode, options, key);
+  }
+
   const tag = resolveTag(node);
 
   // Some nodes (e.g. nested docs) don't render an element themselves.
@@ -268,7 +278,7 @@ function wrapMark(children: VNode | string, mark: SbRichTextMark, options: SbVue
   const Custom = resolveComponentOverride(mark.type, options.components);
   if (Custom) {
     const childContent = typeof children === 'string' ? createTextVNode(children) : children;
-    return h(Custom, { ...mark }, {
+    return h(Custom, { ...mark, context: options }, {
       default: () => [childContent],
     });
   }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7b0b03fbe..47b6448f3 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -842,9 +842,15 @@ importers:
 
   packages/react:
     dependencies:
+      '@storyblok/api-client':
+        specifier: workspace:*
+        version: link:../capi-client
       '@storyblok/js':
         specifier: workspace:*
         version: link:../js
+      '@storyblok/live-preview':
+        specifier: workspace:*
+        version: link:../live-preview
       '@storyblok/richtext':
         specifier: workspace:*
         version: link:../richtext
@@ -21926,7 +21932,9 @@ snapshots:
 
   '@storyblok/react@file:packages/react(next@13.5.11(@babel/core@7.29.7)(@opentelemetry/api@1.9.0)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)(sass@1.99.0))(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
     dependencies:
+      '@storyblok/api-client': link:packages/capi-client
       '@storyblok/js': link:packages/js
+      '@storyblok/live-preview': link:packages/live-preview
       '@storyblok/richtext': link:packages/richtext
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)