chore: Enhance CI/CD workflows, documentation, and Node versioning

.cursor/skills/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: implement-github-issue
+description: Implement a feature, bug fix, or task described in a GitHub issue by following this repo's development process. Use when the user asks to work on, implement, fix, or execute a GitHub issue (e.g. "work on issue #42", "implement #17", "fix the bug in issue 5").
+---
+
+# Implement a GitHub Issue
+
+Execute the feature, bug fix, or task in a GitHub issue by following the repo's
+development process end-to-end. The authoritative workflow lives in the project
+docs — **read them before doing anything else**, in this order:
+
+1. `project/process.md` — the phased workflow to follow.
+2. `project/rules.md` — Definition of done, coding standards, commits,
+   branches, and PR conventions that gate each phase.
+3. `project/info.md` — repo facts: package name, repository, tech stack,
+   structure, and commands.
+
+Treat those files as the source of truth. If this skill and a project doc ever
+conflict, follow the project doc and tell the user.
+
+## Getting started
+
+You need the issue number. If the user didn't give one, ask. Use the `gh` CLI
+for all GitHub work (`gh issue view <n>`, `gh pr create`, `gh pr ready`, etc.).
+
+## Workflow at a glance
+
+The full detail is in `project/process.md`; do not skip reading it. The phases:
+
+1. Review and verify the issue **[approval]**
+2. Research, analyze, and select the best approach **[approval]**
+3. Scaffold code + write failing tests; open a **draft PR** **[approval]**
+4. Iteratively implement until tests pass **[approval]**
+5. Review and optimize **[approval]**
+6. Integration/e2e tests + coverage **[approval]**
+7. Documentation **[approval]**
+8. Final review and refactor **[approval]**
+9. Review the execution process (meta-changes go in a *separate* PR)
+10. Mark PR ready for review and drive it to merge-ready
+
+## Non-negotiables
+
+- **Pick a track first.** State whether you're on the **Standard** or
+  **Lightweight** track at the start (see `project/process.md` → "Choosing a
+  track") and let the user override it.
+- **Respect approval gates.** Phases marked **[approval]** require explicit user
+  approval before you proceed. Do not race ahead.
+- **Honor the Definition of done.** Before requesting approval to advance a
+  phase, run the relevant checks from `project/rules.md`: `npm test`,
+  `npx tsc --noEmit`, `npm run build`, and `npm run coverage` (target > 90%).
+- **TDD.** Write failing tests before implementation; don't weaken or delete
+  tests to force a pass unless a test is proven wrong (explain why).
+- **Branch + commits.** Branch `<repo>-<issue number>` off an up-to-date `main`;
+  prefix intermediate commits with the phase (`scaffold:`, `implement:`,
+  `optimize:`, `validate:`, `document:`, `refactor:`, `process:`) and reference
+  the issue (e.g. `Refs #42`).
+- **PR title = Conventional Commits.** The PR is squash-merged, so its title
+  (`type(scope): summary`) becomes the landed commit. Open the PR as a draft
+  early so CI runs throughout.
+
+## Handling failures
+
+If tests can't be made to pass, the approach proves wrong mid-implementation, or
+any gate can't be met, **stop and surface the problem to the user with options**
+rather than forcing the happy path. Prefer reverting a bad change over layering
+fixes on top of it.

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+# Runs the Definition-of-done checks on pull requests and pushes to main
+# so every PR has green CI (tests, type-check, and build) before review.
+
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - run: npm ci
+      - run: npx tsc --noEmit
+      - run: npm test
+      - run: npm run build

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - name: Install dependencies
+        run: npm clean-install
+      - name: Generate docs
+        run: npm run docs
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/verify-and-release.yml

@@ -0,0 +1,64 @@
+name: Verify and Release
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read # for checkout
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+      - name: Install dependencies
+        run: npm clean-install
+      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
+        run: npm audit signatures
+      - name: Type-check
+        run: npx tsc --noEmit
+      - name: Test
+        run: npm test
+      - name: Build
+        run: npm run build
+
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    needs: verify
+    permissions:
+      contents: write # to be able to publish a GitHub release
+      issues: write # to be able to comment on released issues
+      pull-requests: write # to be able to comment on released pull requests
+      id-token: write # to enable use of OIDC for trusted publishing and npm provenance
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+          registry-url: https://registry.npmjs.org
+      - name: Install dependencies
+        run: npm clean-install
+      - name: Verify the integrity of provenance attestations and registry signatures for installed dependencies
+        run: npm audit signatures
+      - name: Build
+        run: npm run build
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release

.gitignore

@@ -82,6 +82,9 @@ out
 .nuxt
 dist
 
+# Generated API documentation (regenerate with `npm run docs`)
+docs
+
 # Gatsby files
 .cache/
 # Comment in the public line in if your project uses Gatsby and not Next.js

.nvmrc

@@ -0,0 +1 @@
+v24.18.0