web+docs: a complete, verified, AI-readable documentation platform

.gitattributes

@@ -0,0 +1,23 @@
+# The generated IR files are compared byte-for-byte in CI, so their line
+# endings have to be the same on every platform. The generators normalise
+# the frontend's output to LF; this pins the files themselves so a
+# checkout cannot rewrite them.
+web/apps/web/src/docs/generated/ir.ts text eol=lf
+web/apps/web/src/lib/playground-ir.ts text eol=lf
+
+# The plain-text surfaces are served as-is.
+web/apps/web/public/llms.txt text eol=lf
+web/apps/web/public/llms-full.txt text eol=lf
+
+# Shell scripts must keep LF: CRLF breaks them.
+*.sh text eol=lf
+
+# Binary assets.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.mp4 binary
+*.woff binary
+*.woff2 binary

.github/workflows/ci.yml

@@ -7,6 +7,53 @@ on:
     branches: [ master, main ]
 
 jobs:
+  docs:
+    name: Docs verification
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.4.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        working-directory: web
+        run: bun install --frozen-lockfile
+
+      # Every example on the website is compiled by the real Lithon frontend
+      # and pinned to the repo's regression outputs. This job is what makes
+      # that claim true rather than aspirational: a doc that drifts from the
+      # engine fails the build instead of misleading a reader.
+      - name: Verify every docs example against the real toolchain
+        working-directory: web
+        run: bun run verify:docs
+
+      # The generated IR and the AI-facing surfaces are committed, so they
+      # have to match what the frontend produces today. The generators
+      # normalise line endings, so the comparison is the same on every
+      # platform.
+      - name: Check the generated IR is up to date
+        working-directory: web
+        run: |
+          bun scripts/gen-docs-ir.ts
+          bun scripts/gen-playground-ir.ts
+          git diff --exit-code -- apps/web/src/docs/generated/ir.ts apps/web/src/lib/playground-ir.ts
+
+      - name: Type-check the web app
+        working-directory: web
+        run: bun run typecheck
+
+      - name: Lint the web app
+        working-directory: web
+        run: bun run lint
+
   build-and-test:
     name: Build & Test (Ubuntu x86-64)
     runs-on: ubuntu-latest

.github/workflows/deploy.yml

@@ -49,6 +49,12 @@ jobs:
         working-directory: web
         run: bun run scripts/gen-seo.ts "${{ steps.deployment.outputs.page_url || format('https://{0}.github.io/{1}', github.repository_owner, github.event.repository.name) }}"
 
+      # The AI-facing surfaces: a compact index and the whole documentation as
+      # plain text, both generated from the same registry the site renders.
+      - name: Generate the AI-facing surfaces
+        working-directory: web
+        run: bun run scripts/gen-llms.ts
+
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:

.gitignore

@@ -26,4 +26,7 @@ fuzz_failures/
 
 node_modules/
 
+# Local Python virtualenv for the frontend toolchain.
+.venv/
+
 /nul