fix: gate VitePress docs build in pre-push and PR CI

[jimmyandrade]

Summary

Proposed changes

• Fix the Vercel production deploy failure: CONTRIBUTING.md contained GitHub Actions expression syntax with double braces, which VitePress compiles as Vue interpolation and breaks vitepress build.
• Rephrase affected prose in CONTRIBUTING.md and README.md (and AGENTS.md for consistency).
• Add npm run docs:site (predocs:site + docs:demo + vitepress build) and run it after npm test in pre-push (Lefthook) and PR CI so docs-site regressions fail locally before merge.
• Document VitePress constraints (rephrase or HTML entities — no {% raw %}) and update the Git hooks table for the new pre-push sequence.

Related issue

N/A — follow-up to #776 production deploy failure.

Dependencies added/removed (if applicable)

• N/A

---

Testing

• Manual — reproduced npm run docs:build failure on master, verified fix passes locally
• Manual — lefthook run pre-push runs npm run docs:site after npm test

How to test

1. npm run docs:build on this branch — should complete successfully.
2. Introduce mustache-style double braces in CONTRIBUTING.md prose and run npm run docs:site — should fail (same class of error as the production deploy).
3. On a clean dist/, npm run docs:site alone should succeed via predocs:site.

Test configuration

• Node.js version (if applicable): 26.x (local)
• NPM version (if applicable): 11.x

---

Checklist

• I have added corresponding labels to this PR (like bug, enhancement...);
• My commits follow the Conventional Commits 1.0 Guidelines;
• My code follows the style guidelines of this project;
• I have performed a self-review of my own code;
• I have made changes to the documentation (if applicable);
• My changes generate no new warnings or errors;

[Copilot]

Pull request overview

This PR prevents VitePress docs-site regressions from reaching production by removing problematic {{ ... }} sequences from published markdown and by gating the docs-site build in both pre-push hooks and PR CI.

Changes:

• Rephrase markdown in README.md, CONTRIBUTING.md, and AGENTS.md to avoid VitePress/Vue mustache interpolation pitfalls.
• Add a docs:site script (demo generation + vitepress build) and wire it into pre-push and PR CI after npm test.
• Refactor docs:build to delegate to the new docs:site script.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
README.md	Removes {{ ... }} placeholders from prose to avoid VitePress/Vue interpolation issues.
package.json	Adds docs:site and wires docs:build through it.
lefthook.yml	Runs docs-site build after tests in pre-push; keeps typecheck/depcheck parallelized.
CONTRIBUTING.md	Documents the new docs validation step and warns about VitePress mustache parsing.
AGENTS.md	Mirrors the VitePress/mustache guidance and the docs-site validation expectation.
.github/workflows/pr.yml	Adds a CI step to build the VitePress docs site after npm test.