build: reduce build time and improve CI quality

- Remove agent-markdown-audit from default build (no-op in prod)
- Replace pre-push full build with astro check (saves ~3 min per push)
- Add GitHub Actions CI: type check, format check, audit on every push/PR
- Enable starlightLinksValidator on deploy previews (skip production only)
- Raise maxParallelFileOps from 2 to 8 to reduce Rollup serialization
- Parallelize generate-llms-index.js file reads with async fs/promises
- Add /_astro/* immutable cache headers for content-hashed assets
- Fix incorrect node_bundler comment and remove redundant included_files
- Fix stale output: server comment in astro.config.mjs
- Add build audit report to project-docs/

Author: ravibits

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        # Reads packageManager field from package.json automatically
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Type check
+        run: pnpm astro check
+
+      - name: Format check
+        run: pnpm run format:check
+
+      - name: Agent markdown audit
+        run: node scripts/agent-markdown-audit.js --strict

.simple-git-hooks.json

@@ -1,4 +1,4 @@
 {
   "pre-commit": "pnpm pretty-quick --staged",
-  "pre-push": "if [ -n \"$(git status --porcelain)\" ]; then echo \"❌ Error: You have uncommitted changes. Please commit or stash them before pushing.\"; git status --short; exit 1; fi && echo \"Running build before push...\" && pnpm run generate-search-index && pnpm run build && node scripts/log-preview-url.js"
+  "pre-push": "if [ -n \"$(git status --porcelain)\" ]; then echo \"❌ Error: You have uncommitted changes. Please commit or stash them before pushing.\"; git status --short; exit 1; fi && pnpm astro check && node scripts/log-preview-url.js"
 }

astro.config.mjs

@@ -31,10 +31,9 @@ import { injectAgentHeader } from './src/integrations/inject-agent-header.ts'
 
 // https://astro.build/config
 export default defineConfig({
-  // Switched from 'server' to default (static) to drastically reduce build memory.
-  // Astro 6's Vite Environments API creates separate build contexts per output mode;
-  // 'server' mode processes all 300+ pages through a heavy SSR pipeline.
-  // The few SSR pages (auth, health, admin) already have `prerender = false`.
+  // SSR mode: the Netlify adapter prerendering per-page via `prerender` exports.
+  // Pages without `prerender = false` are statically generated at build time.
+  // Memory-intensive builds: see vite.build settings below.
   output: 'server',
   site: 'https://docs.scalekit.com',
   server: {
@@ -106,9 +105,10 @@ export default defineConfig({
           askAi: '8jKZkVuXS0hG',
         }),
         starlightVideos(),
-        // Links validator disabled in CI to reduce build memory usage.
-        // Run locally with: pnpm astro build (without NETLIFY env var)
-        ...(!process.env.NETLIFY
+        // Links validator: enabled locally and on deploy previews; skipped on production
+        // Netlify builds to reduce peak memory usage.
+        // CONTEXT is set by Netlify: 'production' | 'deploy-preview' | 'branch-deploy'
+        ...(!process.env.NETLIFY || process.env.CONTEXT !== 'production'
           ? [
               starlightLinksValidator({
                 exclude: ['/apis/**'],
@@ -411,8 +411,9 @@ export default defineConfig({
       // Disable gzip size reporting to save memory on large builds
       reportCompressedSize: false,
       rollupOptions: {
-        // Limit parallel file I/O to reduce memory spikes during bundling
-        maxParallelFileOps: 2,
+        // Limit parallel file I/O to reduce memory spikes during bundling.
+        // 8 caps concurrency well below unlimited while reducing serialization vs. the prior value of 2.
+        maxParallelFileOps: 8,
         output: {
           manualChunks(id) {
             if (id.includes('@scalar')) return 'scalar'

netlify.toml

@@ -7,9 +7,9 @@
 
 [functions]
   directory = "netlify/functions"
+  # Bundles Functions 1.x with esbuild. The SSR function (Functions 2.0) is
+  # bundled separately by the Netlify adapter and is not affected by this setting.
   node_bundler = "esbuild"
-  # Ensure Functions 2.0 format is used
-  included_files = ["netlify/functions/**"]
 
 # Local dev: same as `pnpm run start` — `NETLIFY_DEV=1 astro dev` on port 4321.
 # Declare `command` + `targetPort` so Netlify Dev matches astro.config server settings.
@@ -21,7 +21,15 @@
   path = "/*"
   function = "track-agents"
 
-# LLM-friendly files: fresh but cacheable (1 hour)
+# Astro emits content-hashed filenames for all JS/CSS bundles — safe to cache permanently.
+# The hash changes whenever content changes, so immutable is correct here.
+[[headers]]
+  for = "/_astro/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+
+# LLM index files — 1h fresh, 24h stale. All four rules below are intentionally identical;
+# Netlify TOML requires a separate [[headers]] block per path pattern.
 [[headers]]
   for = "/llms.txt"
   [headers.values]

package.json

@@ -6,8 +6,9 @@
   "scripts": {
     "dev": "netlify dev:exec pnpm run start",
     "start": "cross-env NETLIFY_DEV=1 astro dev",
-    "build": "astro build && node scripts/generate-llms-index.js && node scripts/agent-markdown-audit.js",
+    "build": "astro build && node scripts/generate-llms-index.js",
     "agent-markdown:audit": "node scripts/agent-markdown-audit.js",
+    "agent-markdown:audit:strict": "node scripts/agent-markdown-audit.js --strict",
     "preview": "astro preview",
     "astro": "astro",
     "upgrade": "pnpm dlx @astrojs/upgrade",