sunerpy · sunerpy · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026
@@ -0,0 +1,87 @@
+# Builds the CodeGraph website (https://firlab.app/codegraph/) from a pull request's pages against
+# firlab's public main, so a dead link, an unknown component, a page missing in one language, a
+# missing screenshot, a banned word, a malformed home page or a link that leaves /codegraph/ fails
+# before the merge rather than in publish-site.yml after it. Nothing is published and no secret is
+# read, so a fork's pull request runs it the same way. Advisory: not part of CI Success.
+# docs/site/README.md describes the whole path.
+name: Docs site
+
+on:
+  pull_request:
+    paths:
+      - "docs/site/**"
+      - "!docs/site/README.md"
+      - "!docs/site/tools/**"
+      - "docs/cli.md"
+      - "docs/mcp.md"
+      - "docs/ui.md"
+      - "docs/languages.md"
+      - "docs/godot.md"
+      - "docs/troubleshooting.md"
+      - "docs/architecture.md"
+      - "docs/data-model.md"
+      - "docs/equivalence.md"
+      - "docs/grammar-manifest.md"
+      - "docs/embedded-extraction.md"
+      - "docs/benchmark.md"
+      - "docs/benchmark-results.md"
+      - ".github/workflows/docs-site.yml"
+      - ".github/workflows/publish-site.yml"
+
+concurrency:
+  group: docs-site-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Docs site · build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout codegraph-rust
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: codegraph-rust
+          persist-credentials: false
+
+      - name: Checkout firlab
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: sunerpy/firlab
+          path: firlab
+          persist-credentials: false
+
+      # The site installs on its own (its package.json pins pnpm); pnpm before setup-node so the
+      # pnpm cache resolves.
+      - name: Install pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          package_json_file: firlab/codegraph/package.json
+
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version-file: firlab/.node-version
+          cache: pnpm
+          cache-dependency-path: firlab/codegraph/pnpm-lock.yaml
+
+      - name: Sync the pages
+        run: ./firlab/codegraph/scripts/sync-codegraph-docs.sh "$GITHUB_WORKSPACE/codegraph-rust"
+
+      - name: Install the site's dependencies
+        working-directory: firlab/codegraph
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        working-directory: firlab/codegraph
+        run: pnpm build
+
+      # The same check firlab's deploy runs before it publishes the site: both languages were
+      # emitted, every in-site link resolves, and every link, asset and sitemap entry stays under
+      # /codegraph/.
+      - name: Check both languages and the /codegraph/ base
+        working-directory: firlab/codegraph
+        run: ./scripts/check-dist.sh dist
@@ -0,0 +1,111 @@
+# Pushes the pages of the CodeGraph website into sunerpy/firlab, which builds it and publishes it
+# inside firlab.app at https://firlab.app/codegraph/ (firlab: `codegraph/`,
+# `.github/workflows/deploy.yml`). docs/site/README.md describes the whole path.
+#
+# The sync pushes instead of the site pulling: the event that should update the site, a merge here,
+# happens in this repository, and the credential stays here and reaches firlab only. The copy rules
+# and checks live in firlab's sync script, which a local preview runs too, so this workflow and a
+# preview produce the same tree.
+#
+# Needs FIRLAB_DOCS_TOKEN: a fine-grained personal access token for sunerpy/firlab only, with
+# Contents read and write and nothing else. GitHub has no API that creates one, so it is made by
+# hand (docs/site/README.md, "One-time setup"). Without it the first step fails and says so.
+name: Publish site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/site/**"
+      - "!docs/site/README.md"
+      - "!docs/site/tools/**"
+      - "docs/cli.md"
+      - "docs/mcp.md"
+      - "docs/ui.md"
+      - "docs/languages.md"
+      - "docs/godot.md"
+      - "docs/troubleshooting.md"
+      - "docs/architecture.md"
+      - "docs/data-model.md"
+      - "docs/equivalence.md"
+      - "docs/grammar-manifest.md"
+      - "docs/embedded-extraction.md"
+      - "docs/benchmark.md"
+      - "docs/benchmark-results.md"
+      - ".github/workflows/docs-site.yml"
+      - ".github/workflows/publish-site.yml"
+  workflow_dispatch:
+
+# Queue, never cancel: a cancelled run could leave a pushed sync without its successor.
+concurrency:
+  group: publish-site
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Push the site's pages to firlab
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Require the firlab token
+        env:
+          FIRLAB_DOCS_TOKEN: ${{ secrets.FIRLAB_DOCS_TOKEN }}
+        run: |
+          if [ -z "${FIRLAB_DOCS_TOKEN}" ]; then
+            echo "::error::FIRLAB_DOCS_TOKEN is not set, so the site cannot be updated. docs/site/README.md, One-time setup, says how to create it."
+            exit 1
+          fi
+
+      - name: Checkout codegraph-rust
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: codegraph-rust
+          persist-credentials: false
+
+      # Full history, so a rejected push can rebase onto a newer main.
+      - name: Checkout firlab
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: sunerpy/firlab
+          token: ${{ secrets.FIRLAB_DOCS_TOKEN }}
+          path: firlab
+          fetch-depth: 0
+
+      - name: Sync the pages
+        run: ./firlab/codegraph/scripts/sync-codegraph-docs.sh "$GITHUB_WORKSPACE/codegraph-rust"
+
+      - name: Commit and push
+        working-directory: firlab
+        env:
+          SOURCE_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          # `git status`, not `git diff`: a new page is an untracked file, which `git diff` misses.
+          if [ -z "$(git status --porcelain -- codegraph/src)" ]; then
+            echo "the site is already up to date; nothing to push"
+            exit 0
+          fi
+
+          # The sync writes nowhere else; staging the tree by name keeps anything else out.
+          git add -- codegraph/src
+          git -c user.name='codegraph-docs[bot]' \
+              -c user.email='codegraph-docs@users.noreply.github.com' \
+              commit -m "docs(codegraph): sync from codegraph-rust@${SOURCE_SHA:0:7}" \
+                     -m "Source: https://github.com/sunerpy/codegraph-rust/commit/${SOURCE_SHA}"
+
+          # The other product sites' syncs push to the same branch. They touch other directories,
+          # so a rejected push rebases onto the new tip and tries again.
+          for attempt in 1 2 3; do
+            if git push origin HEAD:main; then
+              exit 0
+            fi
+            echo "push rejected (attempt ${attempt}); rebasing onto origin/main"
+            git -c user.name='codegraph-docs[bot]' \
+                -c user.email='codegraph-docs@users.noreply.github.com' \
+                pull --rebase origin main
+          done
+          echo "::error::the sync commit could not be pushed after 3 attempts"
+          exit 1
@@ -121,6 +121,7 @@ handoff. Do not use a narrow test to claim a workspace-wide property.
 | release/install/checksum       | shell/PowerShell fixtures, asset-name checks, archive smoke                                                  | README install section and release workflow contract                         |
 | viewer (`codegraph-ui`, `ui/`) | crate tests over indexed fixtures; `cli_ui`; `make ui-check` (rebuilds and byte-checks the committed bundle) | `ui.md`; `cli.md` for the command                                            |
 | docs/community files           | `python3 scripts/docs-check.py`; formatter; link/anchor checks                                               | update the canonical page, not a duplicate summary                           |
+| website pages (`docs/site/`)   | `docs-check.py`; formatter; firlab's sync + build + `check-dist.sh` (`docs-site.yml`)                        | `docs/site/README.md`; both languages; link canonical references, never copy |
 
 If a change alters nodes, edges, reference resolution, file classification, or
 stored graph meaning, decide explicitly whether the extraction version must move.

@@ -13,7 +13,8 @@ native binary. No AI or vector runtime inside the indexer.
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)
 
 [English](README.md) · [简体中文](docs/readme/README.zh-CN.md) ·
-[Documentation](docs/README.md) · [Contributing](CONTRIBUTING.md)
+[Website](https://firlab.app/codegraph/en/) · [Documentation](docs/README.md) ·
+[Contributing](CONTRIBUTING.md)
 
 </div>
 

@@ -4,6 +4,15 @@ The root [README](../README.md) is the landing page. This index points to the
 canonical technical references; update the owning page rather than duplicating
 volatile behavior elsewhere.
 
+## Website
+
+[firlab.app/codegraph](https://firlab.app/codegraph/) (English at
+[`/codegraph/en/`](https://firlab.app/codegraph/en/)) is the user guide, in Chinese
+and English, with screenshots of the browser viewer. Its pages live in
+[`site/`](site/README.md), next to the code they describe; that README explains how
+a change reaches the site, the writing rules and how the screenshots are taken. The
+site publishes the references below unchanged.
+
 ## Use CodeGraph
 
 - [CLI reference](cli.md) — command/path contracts, installation targets,

@@ -228,10 +228,10 @@ codegraph audit --orphans --exclude addons/ -p .   # recommended: denoise vendor
 ```
 
 `-p` selects the **project root**, not a result filter. To scope or denoise the
-report, use the CLI-layer prefix filters `--include <PREFIX>` / `--exclude
-<PREFIX>` (both repeatable, `/`-normalized). For a typical Godot project,
-`--exclude addons/` drops noise from vendored editor plugins; `--include
-<your-content-dir>/` narrows to your own resources.
+report, use the CLI-layer prefix filters `--include <PREFIX>` /
+`--exclude <PREFIX>` (both repeatable, `/`-normalized). For a typical Godot
+project, `--exclude addons/` drops noise from vendored editor plugins;
+`--include <your-content-dir>/` narrows to your own resources.
 
 Because `.tres`/`.tscn`/`project.godot` files have no tree-sitter grammar, they
 get no `file:` graph node and their `ExtResource(…)` references stay in the

@@ -13,7 +13,8 @@
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE-MIT)
 
 [English](../../README.md) · [简体中文](README.zh-CN.md) ·
-[文档](../README.md) · [参与贡献](../../CONTRIBUTING.md)
+[网站](https://firlab.app/codegraph/) · [文档](../README.md) ·
+[参与贡献](../../CONTRIBUTING.md)
 
 </div>