diff --git a/packages/gitlab-mcp-db/README.md b/packages/gitlab-mcp-db/README.md
index 72259bc05..adef98805 100644
--- a/packages/gitlab-mcp-db/README.md
+++ b/packages/gitlab-mcp-db/README.md
@@ -1,6 +1,6 @@
 # Advanced GitLab MCP server
 
-[![npm version](https://img.shields.io/npm/v/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![npm downloads](https://img.shields.io/npm/dm/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE) [![Release](https://github.com/structured-world/gitlab-mcp/workflows/Release/badge.svg)](https://github.com/structured-world/gitlab-mcp/actions) [![Coverage](https://codecov.io/gh/structured-world/gitlab-mcp/graph/badge.svg)](https://codecov.io/gh/structured-world/gitlab-mcp) [![Coverage Report](https://img.shields.io/badge/Coverage-Live%20Report-brightgreen?logo=github)](https://gitlab-mcp.sw.foundation/coverage/)
+[![npm version](https://img.shields.io/npm/v/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![npm downloads](https://img.shields.io/npm/dm/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/structured-world/gitlab-mcp/blob/HEAD/LICENSE) [![Release](https://github.com/structured-world/gitlab-mcp/workflows/Release/badge.svg)](https://github.com/structured-world/gitlab-mcp/actions) [![Coverage](https://codecov.io/gh/structured-world/gitlab-mcp/graph/badge.svg)](https://codecov.io/gh/structured-world/gitlab-mcp) [![Coverage Report](https://img.shields.io/badge/Coverage-Live%20Report-brightgreen?logo=github)](https://gitlab-mcp.sw.foundation/coverage/)
 
 Advanced GitLab MCP server — 58 CQRS tools exposing 230 GitLab operations across 26 entity types. The tool catalog and parameters are filtered to each instance's GitLab version, tier, and token scopes, so the agent sees only what the connected instance actually supports.
 
@@ -161,13 +161,13 @@ The server handles GitLab connectivity issues gracefully:
 
 ## Contributing
 
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development setup, testing, and PR guidelines.
+See [CONTRIBUTING.md](https://github.com/structured-world/gitlab-mcp/blob/HEAD/CONTRIBUTING.md) for development setup, testing, and PR guidelines.
 
 ## Support the Project
 
 <div align="center">
 
-![USDT TRC-20 Donation QR Code](../../packages/gitlab-mcp/assets/usdt-qr.svg)
+![USDT TRC-20 Donation QR Code](https://raw.githubusercontent.com/structured-world/gitlab-mcp/HEAD/packages/gitlab-mcp/assets/usdt-qr.svg)
 
 USDT (TRC-20): `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
 
@@ -175,6 +175,6 @@ USDT (TRC-20): `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
 
 ## License
 
-Apache License 2.0 — see [LICENSE](../../LICENSE) for details.
+Apache License 2.0 — see [LICENSE](https://github.com/structured-world/gitlab-mcp/blob/HEAD/LICENSE) for details.
 
-Based on [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) (MIT). See [LICENSE.MIT](../../LICENSE.MIT).
+Based on [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) (MIT). See [LICENSE.MIT](https://github.com/structured-world/gitlab-mcp/blob/HEAD/LICENSE.MIT).
diff --git a/packages/gitlab-mcp/README.md b/packages/gitlab-mcp/README.md
index 72259bc05..adef98805 100644
--- a/packages/gitlab-mcp/README.md
+++ b/packages/gitlab-mcp/README.md
@@ -1,6 +1,6 @@
 # Advanced GitLab MCP server
 
-[![npm version](https://img.shields.io/npm/v/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![npm downloads](https://img.shields.io/npm/dm/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE) [![Release](https://github.com/structured-world/gitlab-mcp/workflows/Release/badge.svg)](https://github.com/structured-world/gitlab-mcp/actions) [![Coverage](https://codecov.io/gh/structured-world/gitlab-mcp/graph/badge.svg)](https://codecov.io/gh/structured-world/gitlab-mcp) [![Coverage Report](https://img.shields.io/badge/Coverage-Live%20Report-brightgreen?logo=github)](https://gitlab-mcp.sw.foundation/coverage/)
+[![npm version](https://img.shields.io/npm/v/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![npm downloads](https://img.shields.io/npm/dm/@structured-world/gitlab-mcp)](https://www.npmjs.com/package/@structured-world/gitlab-mcp) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/structured-world/gitlab-mcp/blob/HEAD/LICENSE) [![Release](https://github.com/structured-world/gitlab-mcp/workflows/Release/badge.svg)](https://github.com/structured-world/gitlab-mcp/actions) [![Coverage](https://codecov.io/gh/structured-world/gitlab-mcp/graph/badge.svg)](https://codecov.io/gh/structured-world/gitlab-mcp) [![Coverage Report](https://img.shields.io/badge/Coverage-Live%20Report-brightgreen?logo=github)](https://gitlab-mcp.sw.foundation/coverage/)
 
 Advanced GitLab MCP server — 58 CQRS tools exposing 230 GitLab operations across 26 entity types. The tool catalog and parameters are filtered to each instance's GitLab version, tier, and token scopes, so the agent sees only what the connected instance actually supports.
 
@@ -161,13 +161,13 @@ The server handles GitLab connectivity issues gracefully:
 
 ## Contributing
 
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development setup, testing, and PR guidelines.
+See [CONTRIBUTING.md](https://github.com/structured-world/gitlab-mcp/blob/HEAD/CONTRIBUTING.md) for development setup, testing, and PR guidelines.
 
 ## Support the Project
 
 <div align="center">
 
-![USDT TRC-20 Donation QR Code](../../packages/gitlab-mcp/assets/usdt-qr.svg)
+![USDT TRC-20 Donation QR Code](https://raw.githubusercontent.com/structured-world/gitlab-mcp/HEAD/packages/gitlab-mcp/assets/usdt-qr.svg)
 
 USDT (TRC-20): `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
 
@@ -175,6 +175,6 @@ USDT (TRC-20): `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
 
 ## License
 
-Apache License 2.0 — see [LICENSE](../../LICENSE) for details.
+Apache License 2.0 — see [LICENSE](https://github.com/structured-world/gitlab-mcp/blob/HEAD/LICENSE) for details.
 
-Based on [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) (MIT). See [LICENSE.MIT](../../LICENSE.MIT).
+Based on [zereight/gitlab-mcp](https://github.com/zereight/gitlab-mcp) (MIT). See [LICENSE.MIT](https://github.com/structured-world/gitlab-mcp/blob/HEAD/LICENSE.MIT).
diff --git a/packages/gitlab-mcp/README.md.in b/packages/gitlab-mcp/README.md.in
index a1e0bef33..d067ab5c3 100644
--- a/packages/gitlab-mcp/README.md.in
+++ b/packages/gitlab-mcp/README.md.in
@@ -167,7 +167,7 @@ See [CONTRIBUTING.md](__REPO_BASE__/CONTRIBUTING.md) for development setup, test
 
 <div align="center">
 
-![USDT TRC-20 Donation QR Code](__REPO_BASE__/packages/gitlab-mcp/assets/usdt-qr.svg)
+![USDT TRC-20 Donation QR Code](__ASSET_BASE__/packages/gitlab-mcp/assets/usdt-qr.svg)
 
 USDT (TRC-20): `TFDsezHa1cBkoeZT5q2T49Wp66K8t2DmdA`
 
diff --git a/packages/gitlab-mcp/scripts/prepare-release.sh b/packages/gitlab-mcp/scripts/prepare-release.sh
index 9e847e626..039364423 100755
--- a/packages/gitlab-mcp/scripts/prepare-release.sh
+++ b/packages/gitlab-mcp/scripts/prepare-release.sh
@@ -59,29 +59,35 @@ jq --arg v "$VERSION" --arg tc "$TOOL_COUNT" --arg ac "$ACTION_COUNT" --arg ec "
   '.version = $v | .packages[0].version = $v | .description = $tc + " CQRS tools exposing " + $ac + " GitLab operations across " + $ec + " entity types"' \
   server.json > server.tmp && mv server.tmp server.json
 
-# Generate README.md from the template for each location it ships to. __REPO_BASE__
-# is substituted with the path from that README's directory to the repo root, so the
-# repo-relative links (LICENSE, CONTRIBUTING, assets) resolve from every location:
-#   packages/gitlab-mcp/README.md    (npm core page)    -> base ../..
-#   <repo root>/README.md            (GitHub repo page)  -> base .
-#   packages/gitlab-mcp-db/README.md (npm db page)       -> base ../..
+# Generate README.md from the template for each location it ships to. Repo files are
+# referenced through two bases: __REPO_BASE__ for links (LICENSE, CONTRIBUTING) and
+# __ASSET_BASE__ for images. The GitHub repo page resolves paths relative to the
+# repo root. npm does not: it joins a relative path onto the repository URL, which
+# yields a GitHub page address instead of the file, so the READMEs published to npm
+# get absolute bases (blob URLs for links, raw URLs for images).
+#   packages/gitlab-mcp/README.md    (npm core page)    -> absolute
+#   <repo root>/README.md            (GitHub repo page)  -> .
+#   packages/gitlab-mcp-db/README.md (npm db page)       -> absolute
 if [[ ! -f "README.md.in" ]]; then
   echo "ERROR: README.md.in not found" >&2
   exit 1
 fi
+NPM_LINK_BASE="https://github.com/structured-world/gitlab-mcp/blob/HEAD"
+NPM_ASSET_BASE="https://raw.githubusercontent.com/structured-world/gitlab-mcp/HEAD"
 render_readme() {
-  # $1 = output path, $2 = relative path from that README's directory to the repo root
+  # $1 = output path, $2 = link base, $3 = image base
   sed -e "s/__TOOL_COUNT__/${TOOL_COUNT}/g" \
       -e "s/__ACTION_COUNT__/${ACTION_COUNT}/g" \
       -e "s/__ENTITY_COUNT__/${ENTITY_COUNT}/g" \
       -e "s/__READONLY_TOOL_COUNT__/${READONLY_TOOL_COUNT}/g" \
       -e "s/__VERSION__/${VERSION}/g" \
       -e "s|__REPO_BASE__|$2|g" \
+      -e "s|__ASSET_BASE__|$3|g" \
       README.md.in > "$1"
 }
-render_readme README.md ../..
-render_readme ../../README.md .
-render_readme ../gitlab-mcp-db/README.md ../..
+render_readme README.md "$NPM_LINK_BASE" "$NPM_ASSET_BASE"
+render_readme ../../README.md . .
+render_readme ../gitlab-mcp-db/README.md "$NPM_LINK_BASE" "$NPM_ASSET_BASE"
 
 # Update MCP manifest tools list in package.json
 # Uses the list-tools CLI to get full tool definitions and transforms them for manifest