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
Documentation and docs-build tooling only; no runtime engine or API behavior changes. Main operational note is the new generated() hook during docs:build.

Overview
Adds LLM- and coding-agent-oriented documentation outputs on top of the existing VuePress site, without changing the calculation engine.

A new md-companions VuePress plugin runs at docs build time: it strips VuePress-specific markdown (strip.js) and writes a clean .md file beside each HTML page, plus an aggregate llms-full.txt corpus. llms.txt (static) and robots.txt comments point agents at those URLs; context7.json configures Context7 indexing with project-specific rules.

The docs UI gains a global Copy Markdown button (copies the page’s .md URL) and a Set up your coding agent guide with CodingAgentWizard (Claude Code, Cursor, Copilot, etc.). Sidebar and CHANGELOG are updated accordingly.

test/docs/md-companions-strip.spec.js locks in stripper behavior; ESLint adds an override for plain Node **/test/**/*.spec.js specs.

^{Reviewed by Cursor Bugbot for commit ddfa8f0. 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 failed. Why did it fail? →

Name	Link
🔨 Latest commit	ddfa8f0
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a4f38d09b5d610008115419

[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.}

[codecov]

Codecov Report

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

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.

[github-actions]

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

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 497.26 | 493.69 | -0.72%
                                      Sheet B | 157.48 | 157.13 | -0.22%
                                      Sheet T | 141.94 | 142.82 | +0.62%
                                Column ranges | 472.97 |  472.8 | -0.04%
Sheet A:  change value, add/remove row/column |   15.8 |  15.01 | -5.00%
 Sheet B: change value, add/remove row/column | 124.37 | 135.98 | +9.34%
                   Column ranges - add column | 138.43 | 144.84 | +4.63%
                Column ranges - without batch | 427.72 | 454.42 | +6.24%
                        Column ranges - batch | 109.23 | 114.66 | +4.97%