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 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 (12 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 documentation build, static assets, and test/lint config; the spreadsheet engine and runtime API are untouched.

Overview
Adds LLM- and coding-agent-friendly documentation on top of the existing VuePress site: a build-time md-companions plugin writes per-page .md companions and llms-full.txt, using stripVuePressSyntax to remove VuePress-only syntax (containers, Vue components, live demos, etc.).

Site UX: global Copy Markdown link button (absolute .md URL), static llms.txt index, new Set up your coding agent guide with CodingAgentWizard, and context7.json for Context7 indexing. Sidebar and changelog are updated accordingly.

Tooling: Jest coverage for the stripper in test/docs/md-companions-strip.spec.js, an ESLint override for **/test/**/*.spec.js, and Netlify docs builds bumped to Node 22.

^{Reviewed by Cursor Bugbot for commit c0f1ac6. 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	c0f1ac6
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a4f7e8b58bcd000080c1838
😎 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]

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 (c0f1ac6) vs base (4e302ff)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 500.29 | 508.64 | +1.67%
                                      Sheet B | 158.86 |    162 | +1.98%
                                      Sheet T | 142.92 | 144.58 | +1.16%
                                Column ranges | 472.62 | 476.26 | +0.77%
Sheet A:  change value, add/remove row/column |  16.55 |  15.53 | -6.16%
 Sheet B: change value, add/remove row/column | 141.92 | 137.02 | -3.45%
                   Column ranges - add column | 154.65 | 149.23 | -3.50%
                Column ranges - without batch |  436.9 | 436.94 | +0.01%
                        Column ranges - batch | 117.72 | 111.91 | -4.94%

[cursor]

404 page copies missing markdown

Low Severity

The global Copy Markdown link button appears on any path ending in .html, including /404.html, but the md-companions build step deliberately skips that page. Visitors on the 404 page can copy an absolute .md URL that was never published.

Additional Locations (1)

• docs/.vuepress/plugins/md-companions/index.js#L16-L17

 

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

[cursor]

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

There are 3 total unresolved issues (including 2 from previous reviews).

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

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

[cursor]

Unresolved page template placeholders

Medium Severity

The md-companions build writes companions from page._strippedContent, which is raw markdown. VuePress-only tokens like {{ $page.version }} and {{ $page.functionsCount }} are not expanded, so .md companions and llms-full.txt can ship literal placeholders while the HTML site shows real values.

 

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

[codecov]

Codecov Report

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

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.