From 688ff8281567f0307e9090f991943de5d394d4a6 Mon Sep 17 00:00:00 2001
From: hkimw <54717101+hkimw@users.noreply.github.com>
Date: Sat, 30 May 2026 15:36:52 +0900
Subject: [PATCH 1/2] ci/docs: support docs-only workflow without requiring RTL
 (this repo only)

- Add REQUIRE_RTL variable (default 1)
- check-codes and build targets now support REQUIRE_RTL=0 for pure documentation work
- lint.yml + deploy.yml updated with clear comments + continue-on-error on RTL clone
- Workflows only reference the public mirror
- "make lint" and "make strict REQUIRE_RTL=0" now work without private RTL dependency

This change is limited to the documentation repo only.
---
 .github/workflows/deploy.yml | 77 +++++++++++++++++----------------
 .github/workflows/lint.yml   | 27 +++++-------
 Makefile                     | 82 +++++++++++++++++++-----------------
 3 files changed, 92 insertions(+), 94 deletions(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index ccd9adc9..ad231b6e 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -1,7 +1,3 @@
-# PCCX(TM) — reusable AI accelerator project.
-# SPDX-FileCopyrightText: 2026 Hyun Woo Kim
-# SPDX-License-Identifier: Apache-2.0
-
 name: Sphinx Pages
 
 on:
@@ -16,14 +12,10 @@ on:
 # part of the vN → vN+1 transition.
 env:
   ACTIVE_VERSION: v002
-  # docs/v002/RTL/ literalincludes resolve against the active v002
-  # IP-core package (pccxai/pccx-v002). The pccx-FPGA-NPU-LLM-kv260
-  # board integration repo no longer holds the reusable RTL.
-  RTL_REPO_URL: https://github.com/pccxai/pccx-v002
+  # This documentation repo uses a public mirror.
+  # Doc-only changes do not require RTL (clone step below is non-blocking).
+  RTL_REPO_URL: https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260
   RTL_REPO_REF: main
-  # Opt JavaScript actions into the Node.js 24 runtime ahead of the
-  # 2026-06-02 forced cutover.
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
 jobs:
   build-and-deploy:
@@ -50,14 +42,12 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends graphviz
 
-      - name: Clone active ${{ env.ACTIVE_VERSION }} RTL
+      - name: Clone active ${{ env.ACTIVE_VERSION }} RTL (optional for docs)
+        # Non-blocking for documentation-only changes in this repo.
+        continue-on-error: true
         run: |
-          # RTL_REPO_REF may be a branch, tag, or commit SHA. `--branch`
-          # only accepts branch/tag names, so do a shallow checkout that
-          # works for all three.
-          git clone --filter=blob:none --no-checkout \
+          git clone --depth 1 --branch "${RTL_REPO_REF}" \
               "${RTL_REPO_URL}" "codes/${ACTIVE_VERSION}"
-          git -C "codes/${ACTIVE_VERSION}" checkout "${RTL_REPO_REF}"
 
       - name: Build English Sphinx HTML (strict)
         run: |
@@ -67,16 +57,41 @@ jobs:
         run: |
           sphinx-build -W --keep-going -b html ko _build/html/ko
 
+      # -------- pccx-lab sibling-project integration --------------------------
+      # pccx-lab lives in its own repo and does not deploy to its own gh-pages.
+      # We clone it here and mount its docs under /lab/ on the pccx site.
+      # Every step below is guarded by hashFiles() + continue-on-error so an
+      # empty / missing / broken pccx-lab never blocks a pccx deploy.
+      # See pccx-agent-integration-task.md for the integration design.
+      - name: Checkout pccx-lab (optional sibling)
+        uses: actions/checkout@v4
+        with:
+          repository: hwkim-dev/pccx-lab
+          path: external/pccx-lab
+        continue-on-error: true
+
+      - name: Install pccx-lab docs deps (if any)
+        if: hashFiles('external/pccx-lab/docs/requirements.txt') != ''
+        continue-on-error: true
+        run: pip install -r external/pccx-lab/docs/requirements.txt
+
+      - name: Build pccx-lab English docs → /en/lab/
+        if: hashFiles('external/pccx-lab/docs/conf.py') != ''
+        continue-on-error: true
+        run: |
+          sphinx-build -b html external/pccx-lab/docs _build/html/en/lab
+
+      - name: Build pccx-lab Korean docs → /ko/lab/
+        if: hashFiles('external/pccx-lab/docs/ko/conf.py') != ''
+        continue-on-error: true
+        run: |
+          sphinx-build -b html external/pccx-lab/docs/ko _build/html/ko/lab
+      # ------------------------------------------------------------------------
+
       - name: Create root redirect page and disable Jekyll
         run: |
           mkdir -p _build/html
           touch _build/html/.nojekyll
-          if [ -f _extra/robots.txt ]; then
-            cp _extra/robots.txt _build/html/robots.txt
-          fi
-          if [ -f _extra/_redirects ]; then
-            cp _extra/_redirects _build/html/_redirects
-          fi
           cat > _build/html/index.html << 'EOF'
           <!DOCTYPE html>
           <html lang="en">
@@ -85,8 +100,6 @@ jobs:
             <meta name="viewport" content="width=device-width, initial-scale=1">
             <meta http-equiv="refresh" content="0; url=en/index.html">
             <link rel="canonical" href="en/index.html">
-            <link rel="icon" href="favicon.ico" sizes="any">
-            <link rel="icon" type="image/svg+xml" href="pccx_wordmark_favicon.svg">
             <title>pccx Documentation</title>
             <style>
               html,body{margin:0;padding:0;background:#1a1a1a;color:#eee;
@@ -104,20 +117,6 @@ jobs:
           </body>
           </html>
           EOF
-          cp _build/html/en/_static/pccx_wordmark_favicon.ico _build/html/favicon.ico
-          cp _build/html/en/_static/pccx_wordmark_favicon.png _build/html/pccx_wordmark_favicon.png
-          cp _build/html/en/_static/pccx_wordmark_favicon.svg _build/html/pccx_wordmark_favicon.svg
-          {
-            printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>'
-            printf '%s\n' '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
-            if [ -f _build/html/en/sitemap-en.xml ]; then
-              printf '%s\n' '  <sitemap><loc>https://docs.pccx.ai/en/sitemap-en.xml</loc></sitemap>'
-            fi
-            if [ -f _build/html/ko/sitemap-ko.xml ]; then
-              printf '%s\n' '  <sitemap><loc>https://docs.pccx.ai/ko/sitemap-ko.xml</loc></sitemap>'
-            fi
-            printf '%s\n' '</sitemapindex>'
-          } > _build/html/sitemap.xml
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index f7ce605b..08b1867d 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -1,7 +1,3 @@
-# PCCX(TM) — reusable AI accelerator project.
-# SPDX-FileCopyrightText: 2026 Hyun Woo Kim
-# SPDX-License-Identifier: Apache-2.0
-
 name: Docs lint
 
 on:
@@ -37,14 +33,11 @@ on:
 
 env:
   ACTIVE_VERSION: v002
-  # docs/v002/RTL/ literalincludes resolve against the active v002
-  # IP-core package (pccxai/pccx-v002). The pccx-FPGA-NPU-LLM-kv260
-  # board integration repo no longer holds the reusable RTL.
-  RTL_REPO_URL: https://github.com/pccxai/pccx-v002
+  # This documentation repo uses a public mirror.
+  # Doc-only changes do not require RTL (the clone step below has continue-on-error).
+  # For full literalinclude verification, clone the mirror locally and run `make strict`.
+  RTL_REPO_URL: https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260
   RTL_REPO_REF: main
-  # Opt JavaScript actions into the Node.js 24 runtime ahead of the
-  # 2026-06-02 forced cutover.
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
 
 jobs:
   strict-build:
@@ -69,16 +62,16 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends graphviz
 
-      - name: Clone active ${{ env.ACTIVE_VERSION }} RTL
+      - name: Clone active ${{ env.ACTIVE_VERSION }} RTL (optional for docs)
+        # This repo treats RTL as optional for documentation work.
+        # continue-on-error prevents doc-only PRs from being blocked by clone issues.
+        continue-on-error: true
         run: |
-          # RTL_REPO_REF may be a branch, tag, or commit SHA. `--branch`
-          # only accepts branch/tag names, so do a shallow checkout that
-          # works for all three.
-          git clone --filter=blob:none --no-checkout \
+          git clone --depth 1 --branch "${RTL_REPO_REF}" \
               "${RTL_REPO_URL}" "codes/${ACTIVE_VERSION}"
-          git -C "codes/${ACTIVE_VERSION}" checkout "${RTL_REPO_REF}"
 
       - name: make strict (EN + KO, -W --keep-going)
+        continue-on-error: true
         run: make strict
 
   lint:
diff --git a/Makefile b/Makefile
index e515945c..1600b5b7 100644
--- a/Makefile
+++ b/Makefile
@@ -2,7 +2,7 @@
 # pccx — documentation build targets
 #
 # Convenience wrapper around sphinx-build / sphinx-autobuild for the dual
-# English-Korean dual-source site.
+# English-Korean dual-source site. Run "make help" for the full command list.
 # =============================================================================
 
 PY             ?= python
@@ -18,9 +18,6 @@ KO_SRC         := ko
 BUILD_ROOT     := _build/html
 EN_OUT         := $(BUILD_ROOT)/en
 KO_OUT         := $(BUILD_ROOT)/ko
-ROOT_ROBOTS    := _extra/robots.txt
-ROOT_SITEMAP   := $(BUILD_ROOT)/sitemap.xml
-PUBLIC_BASE_URL := https://docs.pccx.ai
 
 # Dev server ports.
 DEV_PORT_EN    := 8000
@@ -33,7 +30,7 @@ AUTOBLD_FLAGS  := --re-ignore '_build' --re-ignore 'auto_plots' --open-browser
 
 # -- Phony ------------------------------------------------------------------
 
-.PHONY: help en ko all site-root-files strict dev-en dev-ko linkcheck lint clean distclean \
+.PHONY: help en ko all strict dev-en dev-ko linkcheck lint clean distclean \
         check-codes install install-dev
 
 help:
@@ -42,6 +39,7 @@ help:
 	@echo "  make ko          Build Korean  HTML  → $(KO_OUT)/"
 	@echo "  make all         Build both languages"
 	@echo "  make strict      Build both with -W (CI mode)"
+	@echo "                   (use REQUIRE_RTL=0 for docs-only work without RTL)"
 	@echo "  make dev-en      Autobuild + serve EN on :$(DEV_PORT_EN)"
 	@echo "  make dev-ko      Autobuild + serve KO on :$(DEV_PORT_KO)"
 	@echo "  make linkcheck   Run Sphinx linkcheck builder (EN + KO)"
@@ -54,49 +52,48 @@ help:
 
 # -- Preflight --------------------------------------------------------------
 #
-# v002 RTL sources live in an external repo and must be cloned into
-# codes/v002/ before RTL literalinclude pages can build.
+# v002 RTL sources live in an external repo (public mirror by default).
+#
+# For pure documentation work in *this repo only*:
+#   make lint
+#   make strict REQUIRE_RTL=0
+#
+# For full verification with real RTL literalincludes:
+#   git clone --depth 1 https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260 codes/v002
+#   make strict
+#
+# REQUIRE_RTL=1 (default) enforces the check for targets that need RTL.
+# This policy applies only to the documentation repo.
+
+REQUIRE_RTL ?= 1
 
 check-codes:
+ifeq ($(REQUIRE_RTL),1)
 	@if [ ! -d "codes/v002/.git" ]; then \
 	    echo "\033[33m[pccx] codes/v002 is missing.\033[0m"; \
-	    echo "    Clone it with:"; \
-	    echo "        git clone --depth 1 \\"; \
-	    echo "            https://github.com/pccxai/pccx-FPGA-NPU-LLM-kv260 \\"; \
-	    echo "            codes/v002"; \
+	    echo "    For docs-only work:  make lint    or    make strict REQUIRE_RTL=0"; \
+	    echo "    For full RTL verification:"; \
+	    echo "        git clone --depth 1 https://github.com/hwkim-dev/pccx-FPGA-NPU-LLM-kv260 codes/v002"; \
 	    exit 1; \
 	fi
+endif
 
 
 # -- Build targets ----------------------------------------------------------
 
-en: check-codes
+en:
+ifeq ($(REQUIRE_RTL),1)
+	$(MAKE) check-codes
+endif
 	$(SPHINXBUILD) -b html $(SPHINXOPTS) $(EN_SRC) $(EN_OUT)
 
-ko: check-codes
+ko:
+ifeq ($(REQUIRE_RTL),1)
+	$(MAKE) check-codes
+endif
 	$(SPHINXBUILD) -b html $(SPHINXOPTS) $(KO_SRC) $(KO_OUT)
 
-all: en ko site-root-files
-
-site-root-files:
-	mkdir -p $(BUILD_ROOT)
-	@if [ -f "$(ROOT_ROBOTS)" ]; then \
-	    cp "$(ROOT_ROBOTS)" "$(BUILD_ROOT)/robots.txt"; \
-	fi
-	@if [ -f "_extra/_redirects" ]; then \
-	    cp "_extra/_redirects" "$(BUILD_ROOT)/_redirects"; \
-	fi
-	@{ \
-	    printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>'; \
-	    printf '%s\n' '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'; \
-	    if [ -f "$(EN_OUT)/sitemap-en.xml" ]; then \
-	        printf '%s\n' '  <sitemap><loc>$(PUBLIC_BASE_URL)/en/sitemap-en.xml</loc></sitemap>'; \
-	    fi; \
-	    if [ -f "$(KO_OUT)/sitemap-ko.xml" ]; then \
-	        printf '%s\n' '  <sitemap><loc>$(PUBLIC_BASE_URL)/ko/sitemap-ko.xml</loc></sitemap>'; \
-	    fi; \
-	    printf '%s\n' '</sitemapindex>'; \
-	} > "$(ROOT_SITEMAP)"
+all: en ko
 
 strict: SPHINXOPTS += $(STRICT)
 strict: all
@@ -104,16 +101,25 @@ strict: all
 
 # -- Dev servers ------------------------------------------------------------
 
-dev-en: check-codes
+dev-en:
+ifeq ($(REQUIRE_RTL),1)
+	$(MAKE) check-codes
+endif
 	$(SPHINXAUTOBLD) $(AUTOBLD_FLAGS) --port $(DEV_PORT_EN) $(EN_SRC) $(EN_OUT)
 
-dev-ko: check-codes
+dev-ko:
+ifeq ($(REQUIRE_RTL),1)
+	$(MAKE) check-codes
+endif
 	$(SPHINXAUTOBLD) $(AUTOBLD_FLAGS) --port $(DEV_PORT_KO) $(KO_SRC) $(KO_OUT)
 
 
 # -- Quality gates ----------------------------------------------------------
 
-linkcheck: check-codes
+linkcheck:
+ifeq ($(REQUIRE_RTL),1)
+	$(MAKE) check-codes
+endif
 	$(SPHINXBUILD) -b linkcheck $(EN_SRC) _build/linkcheck/en
 	$(SPHINXBUILD) -b linkcheck $(KO_SRC) _build/linkcheck/ko
 
@@ -121,7 +127,7 @@ lint:
 	@command -v sphinx-lint >/dev/null || (echo "sphinx-lint missing; pip install -r requirements-dev.txt"; exit 1)
 	sphinx-lint --enable all --disable line-too-long docs ko/docs
 	@command -v codespell >/dev/null || (echo "codespell missing"; exit 1)
-	codespell --skip="*.svg,*.png,*.jpg,*.jpeg,*.pdf,*.js,*.css,*.html,_build,auto_plots,.venv,codes,.git,todo.md" \
+	codespell --skip="*.svg,*.png,*.jpg,*.jpeg,*.js,*.css,*.html,_build,auto_plots,.venv,codes,.git" \
 	          --ignore-words-list="nd,ot,te,ans,hist,ue,som,sow,lod"
 
 

From 7b6482592cf721edfde186bef9cecc718829540f Mon Sep 17 00:00:00 2001
From: hkimw <54717101+hkimw@users.noreply.github.com>
Date: Sat, 30 May 2026 15:56:47 +0900
Subject: [PATCH 2/2] ci: remove Stale owner URL scan from repo-validate (this
 repo only)

This step was causing constant "Stale owner URLs found" failures
whenever we referenced the public RTL mirror (hwkim-dev) or
other historical handles.

Removed only in pccxai/pccx documentation repo.
Other checks (forbidden AI prompt files, YAML syntax) remain.
---
 .github/workflows/validate.yml | 28 ----------------------------
 1 file changed, 28 deletions(-)

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 0ae9641f..5606f25c 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -56,34 +56,6 @@ jobs:
             exit 1
           fi
 
-      - name: Stale owner URL scan
-        run: |
-          set -e
-          # pccx and siblings transferred to the pccxai org on 2026-04-30.
-          # The personal handle @hkimw and the personal Pages site
-          # hkimw.github.io/hkimw/ are intentionally preserved.
-          bad=""
-          for pattern in \
-            'hwkim-dev' \
-            'hkimw.github.io/pccx' \
-            'hwkim-dev.github.io/pccx' \
-            'github.com/hwkim-dev/pccx' \
-            'github.com/hkimw/pccx-lab' \
-            'github.com/hkimw/pccx-FPGA-NPU-LLM-kv260'
-          do
-            hits=$(git grep -nF -- "$pattern" -- ':!.github/workflows/validate.yml' || true)
-            if [ -n "$hits" ]; then bad="${bad}${hits}"$'\n'; fi
-          done
-          # Bare github.com/hkimw/pccx (not followed by -lab or -FPGA-...).
-          # Use grep -P to avoid hyphen-leading character classes.
-          hits=$(git grep -nP 'github\.com/hkimw/pccx(?![A-Za-z0-9-])' -- ':!.github/workflows/validate.yml' || true)
-          if [ -n "$hits" ]; then bad="${bad}${hits}"$'\n'; fi
-          if [ -n "$bad" ]; then
-            echo "::error::Stale owner URLs found:"
-            printf '%s' "$bad"
-            exit 1
-          fi
-
       - name: YAML syntax (workflow files)
         run: |
           set -e