Agent-friendly documentation: .md companions, llms.txt, coding-agent guide (HF-154)

[marcin-kordas-hoc]

Context

HF-154 — make the HyperFormula docs friendlier to coding agents and LLMs. On top of the existing VuePress portal this adds:

• Per-page .md companions — every doc page is also served as clean, VuePress-stripped markdown (a build-time md-companions VuePress plugin), plus an aggregate llms-full.txt.
• llms.txt — a top-level index pointing agents at the markdown sources.
• Copy-Markdown button (CopyMarkdownButton.vue) — copies the page's .md URL for pasting into an agent.
• Coding-agent setup guide (docs/guide/setup-coding-agent.md) plus a CodingAgentWizard.vue helper.
• context7.json and a robots.txt update so agent doc-access tooling (Context7 / GitMCP) can discover the sources.

The markdown stripper (md-companions/strip.js) is the fidelity-critical piece: it turns VuePress-flavoured markdown (::: containers, <script>/Vue components, [[toc]], live :::example demos, nested code fences) into clean markdown for the .md companions and llms.txt.

How did you test your changes?

• The stripper is covered by test/docs/md-companions-strip.spec.js — a .js Jest spec discovered by the default test/**/*spec.(ts|js) glob (9 assertions, all passing). Being a .js file it is skipped by Karma (which only globs .spec.ts); the stripper is plain Node code, not part of the browser bundle.
• Added an ESLint override for **/test/**/*.spec.js (node env, require of untyped modules) so the new spec lints clean.
• npm run lint reports no new errors.

Note: the md-companions generated() hook runs during docs:build (the "Build docs" CI job); the stripper logic itself is covered by the unit spec above.

Types of changes

• New feature or improvement (a non-breaking change that adds functionality)
• Change to the documentation

Related issues:

1. HF-154

Checklist:

• I have reviewed the guidelines about Contributing to HyperFormula and I confirm that my code follows the code style of this project.
• I described my changes in the CHANGELOG.md file.

Notes

• Supersedes Agent-friendly documentation: .md companions, llms.txt, coding-agent guide (HF-154) #1696. That PR was opened from a fork, so its CI could not check out the private hyperformula-tests repo (lint/test/performance failed with a get-a-repository 404). This branch lives on the upstream repo so CI runs with test-repo access.
• Dropped the out-of-scope scripts/extract-public-api.js (an internal review-harness helper with no consumer in this repo) and its scripts/*.js ESLint carve-out. This also resolves the two review threads on Agent-friendly documentation: .md companions, llms.txt, coding-agent guide (HF-154) #1696 that targeted that file (the CodeQL "indirect uncontrolled command line" alert and Cursor's extractHyperFormulaExports regex finding).
• Merged current develop.

Note on the Astro migration

The docs-portal Astro migration (#1686) is a separate track. If it lands first it would supersede this VuePress plumbing (the md-companions plugin and .vue components are VuePress-specific); the agent-friendly outputs (.md companions, llms.txt, coding-agent guide) would need re-homing in Astro. Flagging so the two tracks can be sequenced.

---

Note

Low Risk
Changes are limited to docs build tooling, static assets, and lint/test config; the calculation engine and runtime API are untouched.

Overview
Adds agent-friendly documentation on top of the existing VuePress site: a build-time md-companions plugin writes stripped per-page .md files beside each HTML page and a combined llms-full.txt, using stripVuePressSyntax to remove Vue components, [[toc]], live :::example blocks, and similar syntax while keeping code fences safe.

Docs UX includes a global Copy Markdown link button, a new Set up your coding agent guide with CodingAgentWizard, static llms.txt, and root context7.json for Context7/GitMCP discovery. CHANGELOG documents the feature; Netlify build Node is bumped 18 → 22; ESLint gets an override for plain Node test/**/*.spec.js specs covering the stripper.

^{Reviewed by Cursor Bugbot for commit 01072d5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[qunabu]

Task linked: HF-154 Agent-friendly docs

[netlify]

✅ Deploy Preview for hyperformula-dev-docs ready!

Name	Link
🔨 Latest commit	01072d5
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a4f59f094c56d000795ef20
😎 Deploy Preview	https://deploy-preview-1703--hyperformula-dev-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit ddfa8f0. Configure here.}

[cursor]

Homepage omitted from companions

Medium Severity

The md-companions build only processes pages whose path ends with .html, but VuePress gives docs/index.md the path /. That landing page is skipped, so no root index.md companion is emitted and it is missing from llms-full.txt. CopyMarkdownButton uses the same .html check, so the button never appears on the docs home page.

Additional Locations (1)

• docs/.vuepress/components/CopyMarkdownButton.vue#L19-L21

 

^{Reviewed by Cursor Bugbot for commit ddfa8f0. Configure here.}

[github-actions]

Performance comparison of head (c0cc9c5) vs base (4e302ff)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 509.39 | 506.22 | -0.62%
                                      Sheet B | 167.14 | 162.82 | -2.58%
                                      Sheet T | 146.86 | 143.18 | -2.51%
                                Column ranges | 479.81 | 480.08 | +0.06%
Sheet A:  change value, add/remove row/column |  16.06 |  16.07 | +0.06%
 Sheet B: change value, add/remove row/column | 140.37 | 141.25 | +0.63%
                   Column ranges - add column | 143.21 | 153.62 | +7.27%
                Column ranges - without batch | 436.45 |  437.3 | +0.19%
                        Column ranges - batch | 113.38 | 114.57 | +1.05%

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.14%. Comparing base (4e302ff) to head (01072d5).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1703   +/-   ##
========================================
  Coverage    97.14%   97.14%           
========================================
  Files          176      176           
  Lines        15333    15333           
  Branches      3390     3390           
========================================
  Hits         14895    14895           
  Misses         438      438           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.