feat(astro)!: cut over production site to the astro build (develop → main release)

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,8 +1,8 @@
 ---
-name: "🐞 Bug report"
+name: '🐞 Bug report'
 about: A broken link, rendering/layout glitch, broken search, or other site bug
-title: "[bug] short description"
-labels: ["bug"]
+title: '[bug] short description'
+labels: ['bug']
 ---
 
 ## What's broken

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
-  - name: 🌐 Browse Engineering Vault
-    url: https://dineshbyte.github.io/engineering-learning-hub/
-    about: Read the lessons, cheat sheets, and interview panels.
-  - name: 💬 General question or idea
-    url: https://github.com/dineshbyte/engineering-learning-hub/discussions
-    about: For open-ended questions or ideas, start a discussion instead of an issue.
+    - name: 🌐 Browse Engineering Vault
+      url: https://dineshbyte.github.io/engineering-learning-hub/
+      about: Read the lessons, cheat sheets, and interview panels.
+    - name: 💬 General question or idea
+      url: https://github.com/dineshbyte/engineering-learning-hub/discussions
+      about: For open-ended questions or ideas, start a discussion instead of an issue.

.github/ISSUE_TEMPLATE/content-fix.md

@@ -1,13 +1,14 @@
 ---
-name: "📝 Content fix (accuracy / clarity / typo)"
+name: '📝 Content fix (accuracy / clarity / typo)'
 about: Report a factual error, an unclear explanation, a broken diagram, or a typo in a lesson
-title: "[fix] <track>/<page>: short description"
-labels: ["content", "fix"]
+title: '[fix] <track>/<page>: short description'
+labels: ['content', 'fix']
 ---
 
 ## Where
 
 <!-- Track and page, and the section/heading if you can. -->
+
 - **Track / page:** <!-- e.g. context-engineering/lessons/0003-codebase-context-chunking-and-rag -->
 - **Section:** <!-- e.g. "Chunk overlap" callout -->
 
@@ -26,4 +27,5 @@ labels: ["content", "fix"]
   correction, link the authoritative source: an RFC, a spec, vendor/standards
   docs (MDN, OWASP, Anthropic/MCP, cloud provider AIP), or a primary paper.
 -->
+
 - <!-- https://… -->

.github/ISSUE_TEMPLATE/new-content.md

@@ -1,13 +1,14 @@
 ---
-name: "✨ New lesson or track"
+name: '✨ New lesson or track'
 about: Propose a new lesson within a track, or a brand-new track
-title: "[new] <topic>"
-labels: ["content", "enhancement"]
+title: '[new] <topic>'
+labels: ['content', 'enhancement']
 ---
 
 ## Proposal
 
 <!-- New lesson in an existing track, or a new track? Name the topic. -->
+
 - **Type:** <!-- new lesson | new track -->
 - **Track:** <!-- existing track name, or "NEW: <proposed track>" -->
 - **Topic:** <!-- e.g. "Reranking strategies" -->
@@ -19,6 +20,7 @@ labels: ["content", "enhancement"]
 ## Difficulty rung
 
 <!-- Where does it sit on the ladder? -->
+
 - [ ] Foundation — the mental model and vocabulary
 - [ ] Core — everyday working knowledge
 - [ ] Senior — trade-offs and failure modes
@@ -31,4 +33,5 @@ labels: ["content", "enhancement"]
 ## Sources
 
 <!-- High-trust references the lesson should be grounded in. -->
+
 - <!-- https://… -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,40 +1,11 @@
-<!--
-  Thanks for contributing to Engineering Vault! Keep PRs small and reviewable.
-  Delete sections that don't apply.
--->
+<!-- Keep PRs small and reviewable. -->
 
 ## What & why
 
 <!-- One or two sentences: what this changes and the reason for it. -->
 
-## Type of change
-
-- [ ] Content — new lesson / track, or reworked existing content
-- [ ] Content fix — typo, clarity, accuracy, or diagram fix
-- [ ] Bug fix — broken link, layout, search, etc.
-- [ ] Feature — site/tooling capability
-- [ ] Chore / docs / CI
-
-## Scope
-
-<!-- Which track(s) and page(s)? e.g. docs/context-engineering/lessons/0003-... -->
-
 ## Checklist
 
-<!-- Tick what applies. The first two are enforced by CI — run them locally first. -->
-
-- [ ] `node scripts/check-broken-links.js` passes (no broken internal links)
-- [ ] `node scripts/validate-content.js` passes (SEO tags, interview `data-level`s, JSON-LD, sitemap in sync)
-- [ ] New/renamed pages are added to `docs/sitemap.xml`
-- [ ] Each page has a unique `<title>` (· Engineering Vault), meta description, canonical, and Open Graph tags
-
-### For content changes
-
-- [ ] **Visual-first:** the concept is carried by diagrams/tables/cards; prose only labels them (passes the "skim with text too small to read" ship test)
-- [ ] **Accurate & cited:** non-obvious claims cite high-trust sources (RFCs, specs, vendor/standards docs) — no claims from memory
-- [ ] **Interview panel** present where expected, with valid `data-level` values (`core` / `senior` / `staff` / `design`)
-- [ ] Quiz options are length-balanced; dark and light modes both legible
-
-## Notes for the reviewer
-
-<!-- Anything non-obvious, trade-offs taken, or follow-ups intentionally left out. -->
+- [ ] `node scripts/check-broken-links.cjs` passes
+- [ ] `node scripts/validate-content.cjs` passes
+- [ ] New/renamed pages added to `docs/sitemap.xml`

.github/workflows/deploy.yml

@@ -0,0 +1,71 @@
+name: Build & Deploy
+
+# Flow: feature branch -> PR -> develop -> PR -> main.
+# - PRs into develop or main run build + validate ONLY (no deploy), so errors
+#   are caught before merge.
+# - Deploy to GitHub Pages happens ONLY on push to main (i.e. when a PR merges
+#   into main). It never runs on PRs, and never on develop.
+
+on:
+    push:
+        branches: [main]
+    pull_request:
+        branches: [main, develop]
+    workflow_dispatch:
+
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+# One deployment at a time; don't cancel an in-progress deploy on main.
+concurrency:
+    group: pages-${{ github.ref }}
+    cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+    build:
+        name: Build & validate
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - uses: pnpm/action-setup@v4
+              with:
+                  version: 10 # any pnpm 10 satisfies the lockfile; bump to match local if needed
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+                  cache: pnpm
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+
+            - name: Build site
+              run: pnpm build
+
+            - name: Validate content (SEO, structured-data, sitemap)
+              run: node scripts/validate-content.cjs
+
+            - name: Check internal links
+              run: node scripts/check-broken-links.cjs
+
+            - name: Upload Pages artifact
+              uses: actions/upload-pages-artifact@v3
+              with:
+                  path: docs/
+
+    deploy:
+        name: Deploy to GitHub Pages
+        needs: build
+        # Only deploy on pushes to main, never on PRs or other branches.
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        runs-on: ubuntu-latest
+        environment:
+            name: github-pages
+            url: ${{ steps.deployment.outputs.page_url }}
+        steps:
+            - name: Deploy
+              id: deployment
+              uses: actions/deploy-pages@v4

.github/workflows/pr-title.yml

@@ -0,0 +1,49 @@
+name: PR title
+
+# A squash merge uses the PR *title* as the commit subject, so the title must
+# pass the same Conventional Commits rules that commitlint enforces on local
+# commit messages. This reuses the repo's commitlint.config.js (one source of
+# truth) instead of a separate action with its own type list.
+#
+# Kept out of deploy.yml on purpose: this must also run when a title is EDITED,
+# and pulling the `edited` type into the build workflow would re-run the full
+# Astro build on every title/description tweak. `synchronize` is included so the
+# check re-stamps each new head SHA — required if you make it a required status
+# check in branch protection.
+on:
+    pull_request:
+        types: [opened, edited, synchronize, reopened]
+
+permissions:
+    contents: read
+
+# Newer runs for the same PR supersede older ones.
+concurrency:
+    group: pr-title-${{ github.event.pull_request.number }}
+    cancel-in-progress: true
+
+jobs:
+    lint-title:
+        name: Conventional PR title
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - uses: pnpm/action-setup@v4
+              with:
+                  version: 10
+
+            - uses: actions/setup-node@v4
+              with:
+                  node-version: 22
+                  cache: pnpm
+
+            - name: Install dependencies
+              run: pnpm install --frozen-lockfile
+
+            - name: Lint PR title with commitlint
+              # The title is attacker-controlled, so pass it via env — never inline it
+              # into the shell command (avoids command injection from a crafted title).
+              env:
+                  PR_TITLE: ${{ github.event.pull_request.title }}
+              run: echo "$PR_TITLE" | pnpm exec commitlint

.gitignore

@@ -1,4 +1,5 @@
 # Build and output directories
+docs/
 dist/
 coverage/
 .turbo/
@@ -29,63 +30,34 @@ pnpm-debug.log*
 .DS_Store
 .scannerwork/
 plans
-.superpowers
 specs
+.superpowers
 
 # Test coverage
 .nyc_output/
 .jest-cache
 !/.vscode/
 
 # Personal tooling / internal — excluded from the public repo
-.claude/
+.claude
 _send_to_kindle/
 # EPUBs are personal/local only — readers use the website, not downloads
 *.epub
 *.epub.orig
 *.epub.prev
 
-# In-browser EPUB reader + its local static server are personal/local only —
-# kept on disk but not published (the public site is pure static HTML).
-reader.html
-server.js
-lib/
-package.json
-pnpm-lock.yaml
-pnpm-workspace.yaml
-package-lock.json
 
 # ai configuration ignore file
 .auto-claude/
 .agents
 .cursor
-settings.local.json
-.claude/settings.local.json
-CLAUDE.local.md
-
-# Claude personal task board
-.claude/tasks/todo.md
-.claude/tasks/archive/
-
-# Claude async audit hook artifacts (background auditor output + lockfile)
-.claude/.audit.log
-.claude/.audit-*.lock
-
-# graphify output
-graphify-out/manifest.json
-graphify-out/cost.json
-graphify-out/cache/
-graphify-out/.graphify_*
-graphify-out/graph.json
-graphify-out/graph.html
-
-# stray local debug log artifacts (snuck into a commit once via lint-staged)
-current_logs.log*
-**/current_logs.log*
-
-# Logs ignore files
-logs/
 
 # Python bytecode cache (from scripts/*.py)
 __pycache__/
 *.pyc
+
+# Astro build cache
+.astro/
+
+# per-track working notes — local only (kept on disk, not published)
+notes/

.husky/commit-msg

@@ -0,0 +1,4 @@
+# Validate the commit message against Conventional Commits (commitlint).
+# $1 is the path to the file holding the proposed message. Local-only — CI
+# never commits, and husky itself isn't installed in CI (see install.mjs).
+pnpm exec commitlint --edit "$1"

.husky/install.mjs

@@ -0,0 +1,16 @@
+// Husky installer guard — git hooks are a LOCAL dev aid only.
+//
+// `prepare` runs on every `pnpm install`, including in CI. The pre-commit
+// Prettier hook is meaningless there (CI never commits, and formatting is a
+// local concern — CI validates the built site, it doesn't format source), so
+// we skip the install entirely when CI is set.
+//
+// GitHub Actions (and virtually every CI provider) export CI=true, so this
+// needs no workflow change: `pnpm install --frozen-lockfile` simply no-ops the
+// hook setup. Locally, CI is unset, so hooks install as normal.
+if (process.env.CI) {
+    process.exit(0);
+}
+
+const husky = (await import('husky')).default;
+husky();

.husky/pre-commit

@@ -0,0 +1,4 @@
+# Fast, format-only gate: Prettier-fix just the staged files (lint-staged
+# re-stages them). Heavy checks (astro build, validate-content, broken-links)
+# run in CI — too slow to block every commit, and they need a built docs/.
+pnpm exec lint-staged