From ed693eee276d40566ae4f374bbfade82ed16b356 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Tue, 17 Mar 2026 15:42:59 +0100
Subject: [PATCH 1/2] docs: migrate hosting from GitHub Pages to IC asset
 canister

- Remove /icp-cli/ base prefix from astro config and version switcher
- Add IC asset canister config (icp.yaml, .ic-assets.json5, .well-known/ic-domains)
- Add docs-deploy.yml workflow to deploy docs-deployment branch to IC mainnet
- Update docs.yml to push built assets to docs-deployment instead of gh-pages
- Update VERSIONED_DOCS.md, CONTRIBUTING.md, and README with new deployment info

The docs-deployment branch has been bootstrapped from gh-pages (path rewrites
applied) and is already deployed to ak73b-maaaa-aaaad-qlbgq-cai.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/CONTRIBUTING.md                       |  4 +-
 .github/workflows/docs-deploy.yml             | 38 ++++++++
 .github/workflows/docs.yml                    | 60 +++++--------
 docs-site/.ic-assets.json5                    | 30 +++++++
 docs-site/README.md                           | 30 ++++---
 docs-site/astro.config.mjs                    |  7 +-
 docs-site/icp.yaml                            |  9 ++
 docs-site/public/.well-known/ic-domains       |  1 +
 .../src/components/VersionSwitcher.astro      | 14 ++-
 docs-site/test-version-switcher.sh            | 52 ++++++-----
 docs/VERSIONED_DOCS.md                        | 88 ++++++++-----------
 11 files changed, 194 insertions(+), 139 deletions(-)
 create mode 100644 .github/workflows/docs-deploy.yml
 create mode 100644 docs-site/.ic-assets.json5
 create mode 100644 docs-site/icp.yaml
 create mode 100644 docs-site/public/.well-known/ic-domains

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 721629896..908fd97ab 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -80,7 +80,7 @@ If you want to submit a pull request to fix an issue or add a feature, here's a
 
 ## Contributing to Documentation
 
-The documentation lives in the `docs/` directory and is deployed to https://dfinity.github.io/icp-cli/.
+The documentation lives in the `docs/` directory and is deployed to https://cli.icp.build.
 
 ### Documentation Structure
 
@@ -97,7 +97,7 @@ The documentation site uses [Astro](https://astro.build/) with [Starlight](https
 1. **Source files** (`docs/`) are Markdown with minimal YAML frontmatter (title + description)
 2. **Starlight** reads directly from `docs/` via the glob content loader
 3. **Rehype plugin** (`docs-site/plugins/rehype-rewrite-links.mjs`) rewrites `.md` links at build time for Starlight's clean URLs
-4. **GitHub Actions** automatically deploys to GitHub Pages on push to main
+4. **GitHub Actions** automatically builds and deploys to an IC asset canister on push to main
 
 This architecture keeps source docs GitHub-friendly (`.md` links work on GitHub) while producing clean URLs on the documentation site.
 
diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml
new file mode 100644
index 000000000..ccfc20641
--- /dev/null
+++ b/.github/workflows/docs-deploy.yml
@@ -0,0 +1,38 @@
+name: Deploy Docs to Internet Computer
+
+on:
+  push:
+    branches: [docs-deployment]
+  workflow_dispatch:
+
+concurrency:
+  group: ic-docs-deploy
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: IC mainnet
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout docs-deployment branch
+        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
+        with:
+          ref: docs-deployment
+
+      - name: Install icp-cli
+        run: npm i -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
+
+      - name: Import deploy identity
+        run: |
+          mkdir -p ~/.local/share/icp-cli/identity/keys
+          echo "$ICP_IDENTITY" | base64 -d > ~/.local/share/icp-cli/identity/keys/deployer.pem
+          sed -i 's/\\r\\n/\r\n/g' ~/.local/share/icp-cli/identity/keys/deployer.pem
+          icp identity import deployer --from-pem ~/.local/share/icp-cli/identity/keys/deployer.pem --storage plaintext
+          icp identity default deployer
+        env:
+          ICP_IDENTITY: ${{ secrets.DFX_IDENTITY_DESIGN_TEAM }}
+
+      - name: Deploy to IC mainnet
+        run: icp deploy -e ic docs
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 2852b7f47..56b70295a 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -18,18 +18,11 @@ on:
       - '.github/workflows/docs.yml'
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: write
 
 env:
-  # Site configuration - customize these for forks
-  # Production (dfinity/icp-cli):
-  PUBLIC_SITE: https://dfinity.github.io
-  PUBLIC_BASE_PREFIX: /icp-cli
-  # Forks should update these values:
-  #   PUBLIC_SITE: https://your-username.github.io
-  #   PUBLIC_BASE_PREFIX: /your-repo-name
+  PUBLIC_SITE: https://cli.icp.build
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
@@ -42,20 +35,6 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Validate required environment variables
-        run: |
-          if [[ -z "${{ env.PUBLIC_SITE }}" ]]; then
-            echo "❌ Error: PUBLIC_SITE environment variable is not set"
-            exit 1
-          fi
-          if [[ -z "${{ env.PUBLIC_BASE_PREFIX }}" ]]; then
-            echo "❌ Error: PUBLIC_BASE_PREFIX environment variable is not set"
-            exit 1
-          fi
-          echo "✅ Required environment variables are set:"
-          echo "  PUBLIC_SITE=${{ env.PUBLIC_SITE }}"
-          echo "  PUBLIC_BASE_PREFIX=${{ env.PUBLIC_BASE_PREFIX }}"
-
       - name: Checkout
         uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
 
@@ -76,9 +55,8 @@ jobs:
         env:
           NODE_ENV: production
           PUBLIC_SITE: ${{ env.PUBLIC_SITE }}
-          PUBLIC_BASE_PREFIX: ${{ env.PUBLIC_BASE_PREFIX }}
 
-  # Publish root index and versions list - only runs on main branch
+  # Publish root index, versions list, and IC config files - only runs on main branch
   publish-root-files:
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     needs: build
@@ -94,11 +72,20 @@ jobs:
 
       - name: Prepare root files
         run: |
-          mkdir -p root
+          mkdir -p root/.well-known
 
           # Copy versions.json from repo
           cp docs-site/versions.json root/versions.json
 
+          # Copy IC asset canister config files
+          cp docs-site/icp.yaml root/icp.yaml
+          cp docs-site/.ic-assets.json5 root/.ic-assets.json5
+          mkdir -p root/.icp/data/mappings
+          cp docs-site/.icp/data/mappings/ic.ids.json root/.icp/data/mappings/ic.ids.json
+
+          # Copy custom domain file
+          cp docs-site/public/.well-known/ic-domains root/.well-known/ic-domains
+
           # Extract the latest version from versions.json
           LATEST_VERSION=$(jq -r ".versions[] | select(.latest == true) | .version" docs-site/versions.json)
 
@@ -121,11 +108,12 @@ jobs:
           </html>
           EOF
 
-      - name: Deploy root files to GitHub Pages
+      - name: Deploy root files to docs-deployment branch
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./root
+          publish_branch: docs-deployment
           keep_files: true
 
   # Publish main branch docs for preview (always available at /main/)
@@ -151,19 +139,19 @@ jobs:
       - name: Build main branch docs
         working-directory: ./docs-site
         run: |
-          BASE_PREFIX="${PUBLIC_BASE_PREFIX:-/icp-cli}"
-          echo "Building with base: ${BASE_PREFIX}/main/"
+          echo "Building with base: /main/"
           npm run build
         env:
           NODE_ENV: production
-          PUBLIC_BASE_PATH: ${{ env.PUBLIC_BASE_PREFIX }}/main/
+          PUBLIC_BASE_PATH: /main/
           PUBLIC_SITE: ${{ env.PUBLIC_SITE }}
 
-      - name: Deploy main docs to GitHub Pages
+      - name: Deploy main docs to docs-deployment branch
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs-site/dist
+          publish_branch: docs-deployment
           destination_dir: main
           keep_files: true
 
@@ -189,28 +177,25 @@ jobs:
 
       - name: Extract version from tag or branch
         run: |
-          # Use repo-specific base prefix from env vars (defaults to /icp-cli)
-          BASE_PREFIX="${PUBLIC_BASE_PREFIX:-/icp-cli}"
-
           if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
             # Tag: v0.1.0 -> extract major.minor -> 0.1
             VERSION=${GITHUB_REF#refs/tags/v}
             # Strip patch version (0.1.0 -> 0.1)
             VERSION=${VERSION%.*}
             echo "DOCS_VERSION=${VERSION}" >> $GITHUB_ENV
-            echo "DOCS_BASE_PATH=${BASE_PREFIX}/${VERSION}/" >> $GITHUB_ENV
+            echo "DOCS_BASE_PATH=/${VERSION}/" >> $GITHUB_ENV
           elif [[ "${GITHUB_REF}" == refs/heads/docs/v* ]]; then
             # Branch: docs/v0.1 -> extract version -> 0.1
             VERSION=${GITHUB_REF#refs/heads/docs/v}
             echo "DOCS_VERSION=${VERSION}" >> $GITHUB_ENV
-            echo "DOCS_BASE_PATH=${BASE_PREFIX}/${VERSION}/" >> $GITHUB_ENV
+            echo "DOCS_BASE_PATH=/${VERSION}/" >> $GITHUB_ENV
           else
             echo "❌ Docs should only be published for version tags (v*) or docs branches (docs/v*)"
             echo "Current ref: ${GITHUB_REF}"
             exit 1
           fi
 
-          echo "Building docs for version ${VERSION} with base: ${BASE_PREFIX}/${VERSION}/"
+          echo "Building docs for version ${VERSION} with base: /${VERSION}/"
 
       - name: Build documentation site
         working-directory: ./docs-site
@@ -220,9 +205,10 @@ jobs:
           PUBLIC_BASE_PATH: ${{ env.DOCS_BASE_PATH }}
           PUBLIC_SITE: ${{ env.PUBLIC_SITE }}
 
-      - name: Deploy versioned docs to GitHub Pages
+      - name: Deploy versioned docs to docs-deployment branch
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs-site/dist
+          publish_branch: docs-deployment
           destination_dir: ${{ env.DOCS_VERSION }}
diff --git a/docs-site/.ic-assets.json5 b/docs-site/.ic-assets.json5
new file mode 100644
index 000000000..9b37a8851
--- /dev/null
+++ b/docs-site/.ic-assets.json5
@@ -0,0 +1,30 @@
+[
+  {
+    // Static assets built by Astro — content-hashed filenames, cache forever
+    "match": "**/_astro/**",
+    "headers": {
+      "Cache-Control": "public, max-age=31536000, immutable"
+    }
+  },
+  {
+    // Search index
+    "match": "**/pagefind/**",
+    "headers": {
+      "Cache-Control": "public, max-age=31536000, immutable"
+    }
+  },
+  {
+    // HTML pages — short cache so updates are visible quickly
+    "match": "**/*.html",
+    "headers": {
+      "Cache-Control": "public, max-age=300"
+    }
+  },
+  {
+    // Version list — very short cache so version switcher sees updates quickly
+    "match": "versions.json",
+    "headers": {
+      "Cache-Control": "public, max-age=60"
+    }
+  }
+]
diff --git a/docs-site/README.md b/docs-site/README.md
index 14658e945..3a977c367 100644
--- a/docs-site/README.md
+++ b/docs-site/README.md
@@ -96,23 +96,31 @@ Removes `dist/` and `.astro/` directories
 
 ## Deployment
 
-The site is automatically deployed to GitHub Pages:
-- **URL**: https://dfinity.github.io/icp-cli/
-- **Workflow**: `.github/workflows/docs.yml`
-- **Trigger**: Push to `main` branch (docs or docs-site changes)
+The site is hosted on an IC asset canister and served at `https://cli.icp.build`.
 
-The workflow:
-1. Installs dependencies
-2. Runs `npm run build`
-3. Uploads the `dist/` directory as a GitHub Pages artifact
-4. Deploys to GitHub Pages
+**Canister ID**: `ak73b-maaaa-aaaad-qlbgq-cai`
+
+### How it works
+
+1. **`.github/workflows/docs.yml`** builds documentation and pushes built files to the `docs-deployment` branch (one directory per version: `0.1/`, `0.2/`, `main/`, etc.)
+2. **`.github/workflows/docs-deploy.yml`** triggers on pushes to `docs-deployment` and deploys the entire branch to the IC asset canister
+
+### Triggers
+
+- **Push to `main`**: Rebuilds `/main/` docs and root files (`index.html`, `versions.json`, IC config)
+- **Tags (`v*`)**: Builds versioned docs (e.g., `v0.2.0` → `/0.2/`)
+- **Branches (`docs/v*`)**: Updates versioned docs (e.g., `docs/v0.1` → `/0.1/`)
+
+### Legacy redirect
+
+The old GitHub Pages site at `https://dfinity.github.io/icp-cli/` redirects all paths to `https://cli.icp.build/`.
 
 ## Configuration
 
 ### Site Settings
 In `astro.config.mjs`:
-- `site`: Base URL for the site
-- `base`: Base path (currently `/` for root domain)
+- `site`: Base URL (`https://cli.icp.build` in production)
+- `base`: Version path (set via `PUBLIC_BASE_PATH`, e.g., `/0.2/`, `/main/`)
 - `title`, `description`: Site metadata
 - `logo`: ICP logo configuration
 - `favicon`: Site favicon
diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs
index 340d915db..8646b8648 100644
--- a/docs-site/astro.config.mjs
+++ b/docs-site/astro.config.mjs
@@ -6,10 +6,9 @@ import rehypeRewriteLinks from './plugins/rehype-rewrite-links.mjs';
 // https://astro.build/config
 export default defineConfig({
   site: process.env.PUBLIC_SITE,
-  // For versioned deployments: /icp-cli/0.1/, /icp-cli/0.2/, etc.
-  // For non-versioned: /icp-cli/ in production, / in development
-  // Defaults are set in the workflow, not here
-  base: process.env.PUBLIC_BASE_PATH || (process.env.NODE_ENV === 'production' ? process.env.PUBLIC_BASE_PREFIX + '/' : '/'),
+  // For versioned deployments: /0.1/, /0.2/, etc.
+  // PUBLIC_BASE_PATH is set per-version in CI (e.g., /0.2/, /main/)
+  base: process.env.PUBLIC_BASE_PATH || '/',
   markdown: {
     rehypePlugins: [
       // Rewrite relative .md links for Astro's directory-based output
diff --git a/docs-site/icp.yaml b/docs-site/icp.yaml
new file mode 100644
index 000000000..dd9406463
--- /dev/null
+++ b/docs-site/icp.yaml
@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://github.com/dfinity/icp-cli/raw/refs/heads/main/docs/schemas/icp-yaml-schema.json
+
+canisters:
+  - name: docs
+    recipe:
+      type: "@dfinity/asset-canister@v2.1.0"
+      configuration:
+        version: 0.29.2
+        dir: .
diff --git a/docs-site/public/.well-known/ic-domains b/docs-site/public/.well-known/ic-domains
new file mode 100644
index 000000000..207efb2ff
--- /dev/null
+++ b/docs-site/public/.well-known/ic-domains
@@ -0,0 +1 @@
+cli.icp.build
diff --git a/docs-site/src/components/VersionSwitcher.astro b/docs-site/src/components/VersionSwitcher.astro
index e267c983d..8024365fc 100644
--- a/docs-site/src/components/VersionSwitcher.astro
+++ b/docs-site/src/components/VersionSwitcher.astro
@@ -3,15 +3,11 @@
 const isDev = import.meta.env.DEV;
 const isMainBranch = import.meta.env.BASE_URL?.includes('/main/');
 
-// Extract base prefix and version from BASE_URL
-// Examples: "/icp-cli/0.1/" -> prefix="/icp-cli", version="0.1"
-//           "/your-repo/0.2/" -> prefix="/your-repo", version="0.2"
-const baseUrl = import.meta.env.BASE_URL || '/';
-const basePrefixMatch = baseUrl.match(/^(\/[^\/]+)/);
-const basePrefix = basePrefixMatch ? basePrefixMatch[1] : '';
-
-// Extract version from BASE_URL (e.g., "/icp-cli/0.1/" -> "0.1")
-const versionMatch = baseUrl.match(/\/(\d+\.\d+)\//);
+// No base prefix — versions live at the domain root (/0.1/, /0.2/, /main/)
+const basePrefix = '';
+
+// Extract version from BASE_URL (e.g., "/0.1/" -> "0.1")
+const versionMatch = (import.meta.env.BASE_URL || '/').match(/\/(\d+\.\d+)\//);
 const currentVersion = versionMatch ? versionMatch[1] : 'unknown';
 ---
 
diff --git a/docs-site/test-version-switcher.sh b/docs-site/test-version-switcher.sh
index f0b331619..a8bf5b4e2 100755
--- a/docs-site/test-version-switcher.sh
+++ b/docs-site/test-version-switcher.sh
@@ -19,8 +19,7 @@ cleanup() {
 # Set up trap to catch Ctrl+C and other termination signals
 trap cleanup SIGINT SIGTERM
 
-# Configuration - matches production setup
-BASE_PREFIX="/icp-cli"
+# Configuration - matches production setup (versions at domain root)
 TEST_DIR="dist-test"
 TEST_PORT=4321
 
@@ -32,17 +31,16 @@ echo ""
 # Clean everything for a fresh start
 echo "Cleaning all previous builds and caches..."
 rm -rf "$TEST_DIR" dist .astro
-mkdir -p "$TEST_DIR$BASE_PREFIX"
+mkdir -p "$TEST_DIR"
 
 # Set common environment variables
 export NODE_ENV=production
 export PUBLIC_SITE=http://localhost:4321
-export PUBLIC_BASE_PREFIX="$BASE_PREFIX"
 
 # Function to build a version
 build_version() {
   local version=$1
-  local version_path="${BASE_PREFIX}/${version}/"
+  local version_path="/${version}/"
 
   echo ""
   echo "Building version $version..."
@@ -70,11 +68,11 @@ build_version() {
   echo "  Built with BASE_URL: $BUILT_BASE"
 
   # Copy to test directory
-  mkdir -p "$TEST_DIR$BASE_PREFIX/$version"
-  cp -r dist/* "$TEST_DIR$BASE_PREFIX/$version/"
+  mkdir -p "$TEST_DIR/$version"
+  cp -r dist/* "$TEST_DIR/$version/"
 
   # Verify copy succeeded
-  local file_count=$(ls "$TEST_DIR$BASE_PREFIX/$version" | wc -l)
+  local file_count=$(ls "$TEST_DIR/$version" | wc -l)
   echo "  Copied $file_count files to test directory"
 
   echo "✓ Version $version built successfully"
@@ -88,7 +86,7 @@ build_version "main"
 # Generate test versions.json
 echo ""
 echo "Generating test versions.json..."
-cat > "$TEST_DIR$BASE_PREFIX/versions.json" << 'EOF'
+cat > "$TEST_DIR/versions.json" << 'EOF'
 {
   "$comment": "Test versions.json for local testing",
   "versions": [
@@ -107,7 +105,7 @@ echo "✓ versions.json created"
 # Generate redirect index.html
 echo ""
 echo "Generating root redirect..."
-cat > "$TEST_DIR$BASE_PREFIX/index.html" << EOF
+cat > "$TEST_DIR/index.html" << EOF
 <!doctype html>
 <html>
   <head>
@@ -130,33 +128,33 @@ echo ""
 
 # Verify the structure
 echo "Verifying test structure..."
-echo "Directory: $TEST_DIR$BASE_PREFIX/"
-ls -lah "$TEST_DIR$BASE_PREFIX/"
+echo "Directory: $TEST_DIR/"
+ls -lah "$TEST_DIR/"
 echo ""
 echo "Checking version subdirectories..."
 for version in 0.1 0.2 main; do
     echo ""
-    if [ -d "$TEST_DIR$BASE_PREFIX/$version" ]; then
+    if [ -d "$TEST_DIR/$version" ]; then
         echo "✓ $version/ exists"
-        echo "  Files: $(ls "$TEST_DIR$BASE_PREFIX/$version" | wc -l)"
+        echo "  Files: $(ls "$TEST_DIR/$version" | wc -l)"
 
-        if [ -f "$TEST_DIR$BASE_PREFIX/$version/index.html" ]; then
+        if [ -f "$TEST_DIR/$version/index.html" ]; then
             echo "  index.html: ✓"
 
             # Check BASE_URL in the built HTML
-            BASE_URL_IN_HTML=$(grep -o 'import\.meta\.env\.BASE_URL[^"]*"[^"]*"' "$TEST_DIR$BASE_PREFIX/$version/index.html" | head -1 || echo "not found")
+            BASE_URL_IN_HTML=$(grep -o 'import\.meta\.env\.BASE_URL[^"]*"[^"]*"' "$TEST_DIR/$version/index.html" | head -1 || echo "not found")
             echo "  BASE_URL in HTML: $BASE_URL_IN_HTML"
 
             # Check if version switcher is present
-            if grep -q "version-switcher" "$TEST_DIR$BASE_PREFIX/$version/index.html"; then
+            if grep -q "version-switcher" "$TEST_DIR/$version/index.html"; then
                 echo "  VersionSwitcher: ✓ present"
 
                 # Check what's rendered (dev/main badge or button)
-                if grep -q "version-button" "$TEST_DIR$BASE_PREFIX/$version/index.html"; then
+                if grep -q "version-button" "$TEST_DIR/$version/index.html"; then
                     echo "  Renders: version button (interactive dropdown)"
-                elif grep -q ">main<" "$TEST_DIR$BASE_PREFIX/$version/index.html"; then
+                elif grep -q ">main<" "$TEST_DIR/$version/index.html"; then
                     echo "  Renders: 'main' badge (⚠️ unexpected for $version)"
-                elif grep -q ">dev<" "$TEST_DIR$BASE_PREFIX/$version/index.html"; then
+                elif grep -q ">dev<" "$TEST_DIR/$version/index.html"; then
                     echo "  Renders: 'dev' badge (⚠️ unexpected)"
                 else
                     echo "  Renders: unknown"
@@ -169,8 +167,8 @@ for version in 0.1 0.2 main; do
         fi
 
         # Check for assets directory
-        if [ -d "$TEST_DIR$BASE_PREFIX/$version/_astro" ]; then
-            echo "  _astro/ assets: ✓ ($(ls "$TEST_DIR$BASE_PREFIX/$version/_astro" | wc -l) files)"
+        if [ -d "$TEST_DIR/$version/_astro" ]; then
+            echo "  _astro/ assets: ✓ ($(ls "$TEST_DIR/$version/_astro" | wc -l) files)"
         else
             echo "  _astro/ assets: ✗ MISSING"
         fi
@@ -183,7 +181,7 @@ echo ""
 # Start Python HTTP server (most reliable for static files)
 if ! command -v python3 &> /dev/null; then
     echo "⚠️  Warning: python3 not found. Cannot start server."
-    echo "Files are built in: $TEST_DIR$BASE_PREFIX/"
+    echo "Files are built in: $TEST_DIR/"
 else
     echo "Starting local server with Python..."
     echo "Server starting at: http://localhost:${TEST_PORT}"
@@ -191,10 +189,10 @@ else
     echo "Press Ctrl+C to stop the server when done testing"
     echo ""
     echo "Test URLs:"
-    echo "  - http://localhost:${TEST_PORT}$BASE_PREFIX/ (should redirect to 0.2)"
-    echo "  - http://localhost:${TEST_PORT}$BASE_PREFIX/0.2/ (version 0.2)"
-    echo "  - http://localhost:${TEST_PORT}$BASE_PREFIX/0.1/ (version 0.1)"
-    echo "  - http://localhost:${TEST_PORT}$BASE_PREFIX/main/ (main branch)"
+    echo "  - http://localhost:${TEST_PORT}/ (should redirect to 0.2)"
+    echo "  - http://localhost:${TEST_PORT}/0.2/ (version 0.2)"
+    echo "  - http://localhost:${TEST_PORT}/0.1/ (version 0.1)"
+    echo "  - http://localhost:${TEST_PORT}/main/ (main branch)"
     echo ""
     echo "Expected behavior:"
     echo "  ✓ Version 0.2: Button shows 'v0.2', dropdown shows both versions"
diff --git a/docs/VERSIONED_DOCS.md b/docs/VERSIONED_DOCS.md
index 7fc4e9f3b..5847cc4dd 100644
--- a/docs/VERSIONED_DOCS.md
+++ b/docs/VERSIONED_DOCS.md
@@ -5,70 +5,60 @@ This document explains how the versioned documentation system works for the ICP
 ## Overview
 
 The documentation site supports multiple versions simultaneously:
-- `https://dfinity.github.io/icp-cli/` → Redirects to latest version
-- `https://dfinity.github.io/icp-cli/0.1/` → Version 0.1 docs
-- `https://dfinity.github.io/icp-cli/main/` → Main branch docs (preview)
+- `https://cli.icp.build/` → Redirects to latest version
+- `https://cli.icp.build/0.1/` → Version 0.1 docs
+- `https://cli.icp.build/0.2/` → Version 0.2 docs
+- `https://cli.icp.build/main/` → Main branch docs (preview)
 
 Users can switch between versions using the version switcher dropdown in the header.
 
 ## Architecture
 
-### Directory Structure (gh-pages branch)
+The site is hosted on an IC asset canister (`ak73b-maaaa-aaaad-qlbgq-cai`) and served via the custom domain `cli.icp.build`.
+
+### Deployment branch
+
+All built assets live on the `docs-deployment` branch:
 
 ```
-├── index.html       # Redirects to latest version (or /main/ if no releases)
-├── versions.json    # List of available versions
-├── main/            # Main branch docs (always updated)
-├── 0.1/             # Version 0.1 docs
-├── 0.2/             # Version 0.2 docs
+├── index.html                      # Redirects to latest version (or /main/ if no releases)
+├── versions.json                   # List of available versions
+├── icp.yaml                        # IC asset canister config
+├── .ic-assets.json5                # Asset routing/headers config
+├── .icp/data/mappings/ic.ids.json  # Canister ID mapping
+├── .well-known/ic-domains          # Custom domain verification
+├── main/                           # Main branch docs (always updated)
+├── 0.1/                            # Version 0.1 docs
+├── 0.2/                            # Version 0.2 docs
 └── ...
 ```
 
-### Workflow Triggers
+### Two-workflow pipeline
 
-The workflow [`.github/workflows/docs.yml`](.github/workflows/docs.yml) handles deployment:
+**`.github/workflows/docs.yml`** — builds docs and pushes to `docs-deployment`:
 
 | Trigger | Action |
 |---------|--------|
-| Tag `v*` (e.g., `v0.1.0`) | Deploys to `/0.1/` (major.minor) |
-| Branch `docs/v*` (e.g., `docs/v0.1`) | Updates `/0.1/` (for cherry-picks) |
+| Tag `v*` (e.g., `v0.2.0`) | Deploys to `/0.2/` (major.minor only) |
+| Branch `docs/v*` (e.g., `docs/v0.1`) | Updates `/0.1/` (for cherry-picks / fixes to old versions) |
 | Push to `main` | Deploys to `/main/`, updates root `index.html` and `versions.json` |
 
+**`.github/workflows/docs-deploy.yml`** — deploys `docs-deployment` to the IC:
+
+- Triggers automatically whenever `docs.yml` pushes to `docs-deployment`
+- Runs `icp deploy -e ic docs` using the `DFX_IDENTITY_DESIGN_TEAM` secret
+- Requires the **IC mainnet** GitHub environment
+
 ### Version Switcher
 
 The component ([VersionSwitcher.astro](../docs-site/src/components/VersionSwitcher.astro)):
-- Extracts current version from the URL path at build time
-- Fetches `versions.json` at runtime using the configured base prefix
+- Extracts the current version from the URL path at build time
+- Fetches `/versions.json` at runtime
 - Shows "dev" badge in local development, "main" badge on main branch
 - Shows interactive dropdown with all versions for released docs
 
 ## Configuration
 
-### Environment Variables
-
-Set these in the workflow file to configure deployment:
-
-```yaml
-env:
-  PUBLIC_SITE: https://dfinity.github.io      # GitHub Pages base URL
-  PUBLIC_BASE_PREFIX: /icp-cli                # Repository path prefix
-```
-
-**For forks**, update both values:
-```yaml
-env:
-  PUBLIC_SITE: https://your-username.github.io
-  PUBLIC_BASE_PREFIX: /your-repo-name
-```
-
-The `build` job validates these are set before proceeding.
-
-### GitHub Pages Settings
-
-In **Settings → Pages**:
-- **Source**: Deploy from a branch
-- **Branch**: `gh-pages` / `/ (root)`
-
 ### versions.json
 
 Located at [docs-site/versions.json](../docs-site/versions.json). Update when releasing:
@@ -82,7 +72,7 @@ Located at [docs-site/versions.json](../docs-site/versions.json). Update when re
 }
 ```
 
-The workflow copies this to gh-pages root and generates `index.html` redirecting to the first entry.
+The workflow copies this to the `docs-deployment` root and generates `index.html` redirecting to the version marked `latest: true`.
 
 ## Common Tasks
 
@@ -119,7 +109,7 @@ git commit -m "docs: add v0.2 to version list"
 git push origin main
 ```
 
-**Important**: Push the tag first, then update versions.json to avoid 404s.
+**Important**: Push the tag first, then update `versions.json` to avoid 404s.
 
 ### Update Old Version Docs
 
@@ -129,6 +119,7 @@ git checkout -b docs/v0.1
 # Make changes
 git commit -m "docs: fix typo in v0.1"
 git push origin docs/v0.1
+# → Rebuilds and redeploys /0.1/
 ```
 
 Or push a patch tag (`v0.1.1`) — it deploys to the same `/0.1/` directory.
@@ -143,25 +134,24 @@ git push origin docs/v0.2.0-beta.5
 # → Deploys to /0.2.0-beta.5/
 ```
 
-Don't add beta versions to `versions.json` — they won't appear in the switcher.
+Don't add beta versions to `versions.json` — they won't appear in the version switcher.
 
 ## Local Testing
 
-Run the test script to simulate the full deployment locally:
+Run the test script to simulate multi-version builds locally:
 
 ```bash
 ./docs-site/test-version-switcher.sh
 ```
 
-This builds multiple versions and serves them at `http://localhost:4321/icp-cli/`.
+This builds multiple versions and serves them at `http://localhost:4321`.
 
 ## Troubleshooting
 
 | Problem | Solution |
 |---------|----------|
-| Workflow fails with "environment variable is not set" | Add `PUBLIC_SITE` and `PUBLIC_BASE_PREFIX` to workflow `env:` section |
-| Version switcher shows "Failed to load versions" | Check `versions.json` exists at gh-pages root, check browser console |
+| Version switcher shows "Failed to load versions" | Check `versions.json` exists at `docs-deployment` root, check browser console |
 | Tag pushed but docs not deployed | Verify tag matches `v*` pattern, check workflow logs |
 | New version not in switcher | Push `versions.json` update to main after adding the version |
-| Redirect not working | Check `index.html` in gh-pages, clear browser cache |
-| Deployment replaces other versions | Verify `keep_files: true` and correct `destination_dir` in workflow |
+| Deployment replaces other versions | Verify `keep_files: true` and correct `destination_dir` in the `docs.yml` workflow |
+| Custom domain not resolving | Verify `.well-known/ic-domains` is present on `docs-deployment` and DNS CNAME points to `icp1.io` |

From a0089f711a8ccacb6f67a67e04305a6d52800944 Mon Sep 17 00:00:00 2001
From: Marco Walz <marco.walz@dfinity.org>
Date: Tue, 17 Mar 2026 16:38:39 +0100
Subject: [PATCH 2/2] docs: update custom domain to cli.internetcomputer.org

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/CONTRIBUTING.md                 |  2 +-
 .github/workflows/docs.yml              |  2 +-
 docs-site/README.md                     |  6 +++---
 docs-site/public/.well-known/ic-domains |  2 +-
 docs/VERSIONED_DOCS.md                  | 10 +++++-----
 5 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 908fd97ab..b31fa8633 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -80,7 +80,7 @@ If you want to submit a pull request to fix an issue or add a feature, here's a
 
 ## Contributing to Documentation
 
-The documentation lives in the `docs/` directory and is deployed to https://cli.icp.build.
+The documentation lives in the `docs/` directory and is deployed to https://cli.internetcomputer.org.
 
 ### Documentation Structure
 
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 56b70295a..7cb8991ad 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -22,7 +22,7 @@ permissions:
   contents: write
 
 env:
-  PUBLIC_SITE: https://cli.icp.build
+  PUBLIC_SITE: https://cli.internetcomputer.org
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
diff --git a/docs-site/README.md b/docs-site/README.md
index 3a977c367..6483d3b2e 100644
--- a/docs-site/README.md
+++ b/docs-site/README.md
@@ -96,7 +96,7 @@ Removes `dist/` and `.astro/` directories
 
 ## Deployment
 
-The site is hosted on an IC asset canister and served at `https://cli.icp.build`.
+The site is hosted on an IC asset canister and served at `https://cli.internetcomputer.org`.
 
 **Canister ID**: `ak73b-maaaa-aaaad-qlbgq-cai`
 
@@ -113,13 +113,13 @@ The site is hosted on an IC asset canister and served at `https://cli.icp.build`
 
 ### Legacy redirect
 
-The old GitHub Pages site at `https://dfinity.github.io/icp-cli/` redirects all paths to `https://cli.icp.build/`.
+The old GitHub Pages site at `https://dfinity.github.io/icp-cli/` redirects all paths to `https://cli.internetcomputer.org/`.
 
 ## Configuration
 
 ### Site Settings
 In `astro.config.mjs`:
-- `site`: Base URL (`https://cli.icp.build` in production)
+- `site`: Base URL (`https://cli.internetcomputer.org` in production)
 - `base`: Version path (set via `PUBLIC_BASE_PATH`, e.g., `/0.2/`, `/main/`)
 - `title`, `description`: Site metadata
 - `logo`: ICP logo configuration
diff --git a/docs-site/public/.well-known/ic-domains b/docs-site/public/.well-known/ic-domains
index 207efb2ff..d540913d2 100644
--- a/docs-site/public/.well-known/ic-domains
+++ b/docs-site/public/.well-known/ic-domains
@@ -1 +1 @@
-cli.icp.build
+cli.internetcomputer.org
diff --git a/docs/VERSIONED_DOCS.md b/docs/VERSIONED_DOCS.md
index 5847cc4dd..b5cf2e116 100644
--- a/docs/VERSIONED_DOCS.md
+++ b/docs/VERSIONED_DOCS.md
@@ -5,16 +5,16 @@ This document explains how the versioned documentation system works for the ICP
 ## Overview
 
 The documentation site supports multiple versions simultaneously:
-- `https://cli.icp.build/` → Redirects to latest version
-- `https://cli.icp.build/0.1/` → Version 0.1 docs
-- `https://cli.icp.build/0.2/` → Version 0.2 docs
-- `https://cli.icp.build/main/` → Main branch docs (preview)
+- `https://cli.internetcomputer.org/` → Redirects to latest version
+- `https://cli.internetcomputer.org/0.1/` → Version 0.1 docs
+- `https://cli.internetcomputer.org/0.2/` → Version 0.2 docs
+- `https://cli.internetcomputer.org/main/` → Main branch docs (preview)
 
 Users can switch between versions using the version switcher dropdown in the header.
 
 ## Architecture
 
-The site is hosted on an IC asset canister (`ak73b-maaaa-aaaad-qlbgq-cai`) and served via the custom domain `cli.icp.build`.
+The site is hosted on an IC asset canister (`ak73b-maaaa-aaaad-qlbgq-cai`) and served via the custom domain `cli.internetcomputer.org`.
 
 ### Deployment branch