chore: add strict pre-commit guard

.githooks/pre-commit

@@ -0,0 +1,12 @@
+#!/bin/sh
+set -eu
+
+echo "[pccx] running pre-commit strict Sphinx build..."
+
+if ! make strict; then
+    echo
+    echo "Sphinx strict build failed. Run 'make strict' locally to see warnings."
+    exit 1
+fi
+
+echo "[pccx] strict Sphinx build passed."

.github/workflows/v002-book.yml

@@ -0,0 +1,104 @@
+# PCCX(TM) — reusable AI accelerator project.
+# SPDX-FileCopyrightText: 2026 Hyun Woo Kim
+# SPDX-License-Identifier: Apache-2.0
+
+name: v002-book
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+    paths:
+      - "book/v002/**"
+      - "docs/v002/**"
+      - "_static/cover.tex"
+      - "_static/cover/**"
+      - "_static/colophon.tex"
+      - "conf.py"
+      - "conf_common.py"
+      - "requirements.txt"
+      - "tools/build_v002_book_pdf.sh"
+      - ".github/workflows/v002-book.yml"
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  PDF_PATH: _build/v002-book/pdf/pccx-v002-book-preprint.pdf
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out docs repo
+        uses: actions/checkout@v4
+
+      - name: Clone v002 RTL source for literalincludes
+        env:
+          GH_TOKEN: ${{ secrets.PCCX_BOOKS_RELEASE_TOKEN }}
+        run: |
+          test -n "$GH_TOKEN" || {
+            echo "PCCX_BOOKS_RELEASE_TOKEN is required to read the private v002 source." >&2
+            exit 1
+          }
+          git clone --depth 1 "https://x-access-token:${GH_TOKEN}@github.com/pccx-internal/pccx-v002.git" codes/v002
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+            graphviz \
+            latexmk \
+            poppler-utils \
+            texlive-xetex \
+            texlive-fonts-recommended \
+            texlive-fonts-extra \
+            texlive-lang-korean \
+            texlive-latex-extra \
+            texlive-pictures \
+            texlive-science
+
+      - name: Install Sphinx dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+
+      - name: Build private v002 book PDF
+        run: bash tools/build_v002_book_pdf.sh
+
+      - name: Sanity check PDF
+        run: |
+          test -s "$PDF_PATH"
+          pages="$(pdfinfo "$PDF_PATH" | awk '/^Pages:/ {print $2}')"
+          echo "Built PDF has ${pages:-0} page(s)."
+          test "${pages:-0}" -ge 20
+          python - "$PDF_PATH" <<'PY'
+          import subprocess
+          import sys
+
+          pdf = sys.argv[1]
+          text = subprocess.check_output(["pdftotext", pdf, "-"], text=True, errors="ignore")
+          blocked = ["NVI" + "DIA", "In" + "tel", "in" + "tel", "reg" + "istered", chr(174)]
+          hits = [term for term in blocked if term in text]
+          if hits:
+              print("Blocked term found in extracted PDF text.", file=sys.stderr)
+              sys.exit(1)
+          PY
+
+      - name: Create private release asset
+        env:
+          GH_TOKEN: ${{ secrets.PCCX_BOOKS_RELEASE_TOKEN }}
+        run: |
+          test -n "$GH_TOKEN" || {
+            echo "PCCX_BOOKS_RELEASE_TOKEN is required to publish the private book release." >&2
+            exit 1
+          }
+          stamp="$(date -u +%Y-%m-%dT%H%M%SZ)"
+          tag="v002-book-preprint-${stamp}"
+          gh release create "$tag" "$PDF_PATH" \
+            --repo pccx-internal/pccx-books-private \
+            --target artifact/v002-book-release-anchor \
+            --title "v002 book preprint ${stamp}" \
+            --notes "v002 book preprint ${stamp}"

CONTRIBUTING.md

@@ -15,7 +15,15 @@ Before opening a pull request:
 
 1. Keep changes focused and small.
 2. Explain why the change is useful.
-3. For documentation updates, verify that the affected page builds correctly.
-4. If you are unsure, open an issue first.
+3. Install the repository git hooks once:
+
+   ```bash
+   git config core.hooksPath .githooks
+   ```
+
+4. Run `make strict` before every commit. The local pre-commit hook runs the
+   same command and blocks the commit when Sphinx emits warnings or errors.
+5. For documentation updates, verify that the affected page builds correctly.
+6. If you are unsure, open an issue first.
 
 PCCX is currently research-oriented and evolves quickly, so design discussions are welcome.

_static/colophon.tex

@@ -0,0 +1,21 @@
+\chapter*{Colophon}
+\addcontentsline{toc}{chapter}{Colophon}
+\thispagestyle{plain}
+
+\begin{tabular}{@{}p{0.28\linewidth}p{0.62\linewidth}@{}}
+Title & \texttt{[[TITLE\_PLACEHOLDER]]} \\
+Subtitle & \texttt{[[SUBTITLE\_PLACEHOLDER]]} \\
+Author & \texttt{[[AUTHOR\_PLACEHOLDER]]} \\
+Publisher & Altifigence\texttrademark{} \\
+Representative & Hyun Woo Kim / 김현우 \\
+Business ID & 380-07-03687 \\
+Address & 22017 인천 연수구 랜드마크로 160 \\
+ISBN & \texttt{[[ISBN\_PLACEHOLDER]]} \\
+Build type & Private preprint PDF for ISBN review \\
+\end{tabular}
+
+\vspace{1.5cm}
+
+This PDF is a private publication-review artifact. It is not part of the
+public docs.pccx.ai site build and must be distributed only through the
+private PCCX books artifact repository.

_static/cover.tex

@@ -0,0 +1,41 @@
+\begin{titlepage}
+\thispagestyle{empty}
+\begingroup
+\setlength{\parindent}{0pt}
+\begin{tikzpicture}[remember picture,overlay]
+\node[inner sep=0pt] at (current page.center)
+  {\includegraphics[height=\paperheight]{_static/cover/cover-art.jpg}};
+
+\node[
+  anchor=north west,
+  align=left,
+  inner sep=0pt,
+  text=black,
+  text width=0.76\paperwidth
+] at ([xshift=14mm,yshift=-14mm]current page.north west) {%
+  {\pccxcovermono\bfseries\fontsize{20}{24}\selectfont [[TITLE\_PLACEHOLDER]]\par}
+  \vspace{3mm}
+  {\pccxcoverfont\bfseries\fontsize{12}{16}\selectfont [[SUBTITLE\_PLACEHOLDER]]\par}
+  \vspace{4mm}
+  {\pccxcoverfont\fontsize{9}{12}\selectfont Private Sphinx LaTeX preprint for ISBN review\par}
+};
+
+\node[
+  anchor=south west,
+  align=left,
+  inner sep=0pt,
+  text=black,
+  text width=0.76\paperwidth
+] at ([xshift=14mm,yshift=16mm]current page.south west) {%
+  {\pccxcoverfont\fontsize{10}{13}\selectfont [[AUTHOR\_PLACEHOLDER]]\par}
+  \vspace{1mm}
+  {\pccxcoverfont\fontsize{10}{13}\selectfont Altifigence\texttrademark{}\quad 2026\par}
+  \vspace{1mm}
+  {\pccxcovermono\fontsize{8}{11}\selectfont ISBN [[ISBN\_PLACEHOLDER]]\par}
+};
+\end{tikzpicture}
+
+\null
+\endgroup
+
+\end{titlepage}

book/v002/index.rst

@@ -0,0 +1,18 @@
+PCCX v002 Technical Architecture
+================================
+
+.. only:: html
+
+   This document is the private Sphinx LaTeX build root for the v002 book.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents
+
+   /docs/v002/index
+
+References
+----------
+
+.. bibliography::
+   :all:

conf.py

@@ -73,3 +73,97 @@
 
 bibtex_bibfiles = ["refs.bib"]
 sitemap_filename = "sitemap-en.xml"
+
+
+def _has_sphinx_tag(name: str) -> bool:
+    try:
+        return tags.has(name)  # type: ignore[name-defined]
+    except NameError:
+        return False
+
+
+if not _has_sphinx_tag("v002_book"):
+    exclude_patterns = [
+        *exclude_patterns,
+        "book",
+        "book/**",
+    ]
+
+
+if _has_sphinx_tag("v002_book"):
+    root_doc = "book/v002/index"
+
+    latex_engine = "xelatex"
+    latex_documents = [
+        (
+            "book/v002/index",
+            "pccx-v002-book.tex",
+            "PCCX v002 Technical Architecture",
+            "Altifigence",
+            "manual",
+        ),
+    ]
+    latex_additional_files = [
+        "_static/cover.tex",
+        "_static/cover/cover-art.jpg",
+        "_static/colophon.tex",
+    ]
+    latex_show_urls = "footnote"
+    latex_domain_indices = True
+    latex_elements = {
+        "papersize": "b5paper",
+        "pointsize": "10pt",
+        "sphinxsetup": "iconpackage=none",
+        "fontpkg": r"""
+\usepackage{fontspec}
+\usepackage{xeCJK}
+\IfFontExistsTF{Noto Serif}{\setmainfont{Noto Serif}}{\setmainfont{Latin Modern Roman}}
+\IfFontExistsTF{Noto Sans}{\setsansfont{Noto Sans}}{\setsansfont{Latin Modern Sans}}
+\IfFontExistsTF{Noto Sans Mono}{\setmonofont{Noto Sans Mono}}{\setmonofont{Latin Modern Mono}}
+\IfFontExistsTF{Noto Sans CJK KR}{\setCJKmainfont{Noto Sans CJK KR}}{%
+  \IfFontExistsTF{NanumGothic}{\setCJKmainfont{NanumGothic}}{\setCJKmainfont{UnBatang}}%
+}
+\IfFontExistsTF{Noto Sans CJK KR}{\setCJKsansfont{Noto Sans CJK KR}}{%
+  \IfFontExistsTF{NanumGothic}{\setCJKsansfont{NanumGothic}}{\setCJKsansfont{UnBatang}}%
+}
+\IfFontExistsTF{Noto Sans CJK KR}{\setCJKmonofont{Noto Sans CJK KR}}{%
+  \IfFontExistsTF{NanumGothicCoding}{\setCJKmonofont{NanumGothicCoding}}{\setCJKmonofont{UnBatang}}%
+}
+""",
+        "preamble": r"""
+\setcounter{tocdepth}{2}
+\setcounter{secnumdepth}{3}
+\usepackage{bookmark}
+\usepackage{makeidx}
+\usepackage{newunicodechar}
+\usepackage{tikz}
+\IfFontExistsTF{Pretendard}{\newfontfamily\pccxcoverfont{Pretendard}}{%
+  \IfFontExistsTF{Noto Sans CJK KR}{\newfontfamily\pccxcoverfont{Noto Sans CJK KR}}{%
+    \IfFontExistsTF{NanumGothic}{\newfontfamily\pccxcoverfont{NanumGothic}}{\newfontfamily\pccxcoverfont{Latin Modern Sans}}%
+  }%
+}
+\IfFontExistsTF{Courier New}{\newfontfamily\pccxcovermono{Courier New}}{%
+  \IfFontExistsTF{Noto Sans Mono}{\newfontfamily\pccxcovermono{Noto Sans Mono}}{\newfontfamily\pccxcovermono{Latin Modern Mono}}%
+}
+\titleformat{\chapter}[display]
+  {\normalfont\pccxcovermono\bfseries\huge}
+  {\chaptertitlename\ \thechapter}
+  {12pt}
+  {\Huge}
+\makeindex
+\newunicodechar{→}{\ensuremath{\rightarrow}}
+\newunicodechar{←}{\ensuremath{\leftarrow}}
+\newunicodechar{↔}{\ensuremath{\leftrightarrow}}
+\newunicodechar{≈}{\ensuremath{\approx}}
+\newunicodechar{≲}{\ensuremath{\lesssim}}
+""",
+        "maketitle": r"""
+\input{_static/cover.tex}
+\cleardoublepage
+\input{_static/colophon.tex}
+\cleardoublepage
+\sphinxtableofcontents
+\cleardoublepage
+""",
+        "printindex": r"\printindex",
+    }

conf_common.py

@@ -112,6 +112,7 @@
     "Makefile",
     # planning / audit markdown at the repo root — not part of the docs site
     "USER_ACTIONS.md",
+    "KOREAN_PUBLICATION_EDIT_REPORT.md",
     "pccx_master_roadmap_final.md",
     "pccx_v002_extended_20toks_plan.md",
     "tinynpu_v003_gemma4_e4b_plan*.md",  # the (1) variant uses a paren

docs/v002/RTL/pccx-v002-literalinclude-migration.md

@@ -85,7 +85,7 @@ changes ship together so there is no half-state.
 - No `git push --force` or `--force-with-lease`.
 - No tags pushed.
 - No staging push.
-- No PCCX® claim, no registered-trademark claim, no private
+- No PCCX trademark-registration claim, no private
   trademark filings exposed.
 - No hardware/runtime/timing/bitstream claim is made by this PR;
   it is documentation-only.

docs/v002/RTL/preprocess.md

@@ -31,7 +31,7 @@ are driven to MAT_CORE.
 ```
 
 Accepts a 256-bit AXI-Stream slave (16 × BF16) and produces a 432-bit
-master (16 × 27-bit fixed-point). The conversion spans **3 registered
+master (16 × 27-bit fixed-point). The conversion spans **3 clocked
 pipeline stages**.
 
 - **Stage 1** (`phase / buffer_low / block_valid`): On the even beat,

docs/v002/overview.rst

@@ -2,12 +2,16 @@
 Overview
 ====================
 
-|Status| |Architecture| |Target| |Precision|
+.. only:: html
 
-.. |Status| image:: https://img.shields.io/badge/Status-Active_Development-yellow
-.. |Architecture| image:: https://img.shields.io/badge/Architecture-Heterogeneous_NPU-purple
-.. |Target| image:: https://img.shields.io/badge/Target-Kria_KV260-orange
-.. |Precision| image:: https://img.shields.io/badge/Precision-W4A8-green
+   .. raw:: html
+
+      <p>
+        <img alt="Status: Active Development" src="https://img.shields.io/badge/Status-Active_Development-yellow">
+        <img alt="Architecture: Heterogeneous NPU" src="https://img.shields.io/badge/Architecture-Heterogeneous_NPU-purple">
+        <img alt="Target: Kria KV260" src="https://img.shields.io/badge/Target-Kria_KV260-orange">
+        <img alt="Precision: W4A8" src="https://img.shields.io/badge/Precision-W4A8-green">
+      </p>
 
 1. Project Goal
 ================

ko/docs/evidence/risk-register.md

@@ -38,7 +38,7 @@ orphan: true
 - `pccx-v002/Vision/` 흡수 여부는 호환성 리뷰 후 결정.
 - Voice 도메인 아직 placeholder 상태.
 - ASIC/MPW 탐색은 장기 항목으로 현재는 범위 밖.
-- 상용/스폰서/투자 약관은 모두 [commercial](../commercial/)에서 DRAFT 상태.
+- 상용/스폰서/투자 약관은 모두 [commercial](../commercial/README.md)에서 DRAFT 상태.
 
 ## 이 페이지의 범위
 

ko/docs/ip/trademark-filing-log.md

@@ -59,6 +59,6 @@ Class 09는 open/상용 트랙 문서 및 제품군과의 연계에 대응한다
 
 ## Linked
 
-- 핵심 상표 정책: [`TRADEMARKS.md`](../../TRADEMARKS.md)
+- 핵심 상표 정책: `TRADEMARKS.md`
 - IP 전략: [`docs/ip/`](README.md)
 - 상업 트랙: [`docs/commercial/`](../commercial/README.md)

ko/docs/ip/trademarks.md

@@ -12,7 +12,7 @@ orphan: true
 공식 등록은 아직 확정되지 않았으므로, 현재 목록은 "사용 주장"임을 의미한다.
 
 공식 진입점 및 최신 filing은
-[`TRADEMARKS.md`](../../TRADEMARKS.md)와
+`TRADEMARKS.md`와
 [`trademark-filing-log.md`](trademark-filing-log.md)를 함께 확인한다.
 공개 문서에서 첫 언급에는 `PCCX™`를 사용하고,
 해당 관할권 등록이 완료되기 전에는 `PCCX®`를 쓰지 않는다.