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 plugin), plus an aggregate llms-full.txt. Both are also mirrored to the site root so /llms.txt and /llms-full.txt resolve on GitHub Pages (prod) and the Netlify preview.
• llms.txt — a top-level index pointing agents at the Markdown sources.
• View-as-Markdown link (ViewMarkdownLink.vue) — links to the page's .md source so an agent can open and read it directly.
• 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]], {{ }} bindings, Vue-bound <a :href>/<img :src>, live :::example demos, nested code fences) into clean Markdown.

How did you test your changes?

• Manually verified the stripper on representative inputs (tip/warning containers, nested code fences, Vue-bound <a :href>/<img :src>, [[toc]], <script>/component removal, :::example demos) — confirming code fences, including Vue-shaped samples inside container bodies, survive verbatim while prose is cleaned.
• Sanity-checked the full corpus against the Netlify deploy-preview (llms-full.txt populated, per-page .md clean, no leaked components).
• npm run lint clean.

Note on test coverage

The md-companions stripper currently has no automated regression tests. The earlier test/docs/*.spec.js suites (strip / corpus / generated) were removed in 363a5e2 — the public repo carries smoke tests only (test/README.md), and this is build-time docs tooling, not shipped src/ code, so a stripper regression degrades the generated .md/llms.txt, not engine/product behaviour. The working safety net is Cursor Bugbot + the Netlify deploy-preview + review.

That said, this is the second fidelity bug in the stripper (after the Vue-bound link/image fix), and the removed suites did not cover the case that regressed here — Vue markup inside a code fence sitting inside a container. If we want coverage, the right home is the private hyperformula-tests repo (restore the removed cases + this container-fence intersection).

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 (moved to an upstream branch so CI can access the private hyperformula-tests repo). Current develop is merged in.
• The docs-portal Astro migration (Migrate documentation to Astro Starlight #1686) is a separate track. If it lands first it supersedes this VuePress plumbing (the md-companions plugin and .vue components are VuePress-specific); the agent-friendly outputs (.md companions, llms.txt, setup guide) would need re-homing in Astro.

---

Note

Low Risk
Docs-site and build-time tooling only; no changes to src/ engine behavior. Main operational risk is stripper fidelity regressions in generated .md/llms-full.txt (currently manual/preview validation, no automated stripper tests in this PR).

Overview
Adds LLM/agent-friendly documentation outputs on top of the existing VuePress docs build, without changing the spreadsheet engine.

A new md-companions VuePress plugin runs at build time: it strips VuePress-only syntax (:::example demos, Vue components, [[toc]], bound <a :href> / <img :src>, etc.) via strip.js, resolves injected {{ $page.* }} values, rebases root-relative links for the docs base, and writes a clean .md companion beside each HTML page plus an aggregated llms-full.txt (with absolute links in the corpus). context7.json points Context7-style tooling at the docs folder with project-specific rules.

The local theme injects ViewMarkdownLink (“View as Markdown”) on every page; setup-coding-agent.md and CodingAgentWizard document Claude Code skills, Cursor/Copilot rules, MCP (GitMCP / Context7), and copyable snippets (via clipboard.js). Sidebar and DEV_DOCS.md / docs/README.md are updated accordingly. Netlify build uses Node 22; .eslintrc.js gets a minor override-array syntax fix.

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

[github-actions]

Performance comparison of head (f2e95fc) vs base (23a7437)

                                     testName |   base |   head | change
------------------------------------------------------------------------
                                      Sheet A | 511.85 | 529.05 | +3.36%
                                      Sheet B | 165.58 | 176.26 | +6.45%
                                      Sheet T |  148.8 | 152.94 | +2.78%
                                Column ranges | 482.61 | 492.83 | +2.12%
                                Sorted lookup |  14705 |  14773 | +0.46%
Sheet A:  change value, add/remove row/column |  17.19 |  17.21 | +0.12%
 Sheet B: change value, add/remove row/column | 148.72 | 148.72 |  0.00%
                   Column ranges - add column | 163.37 | 161.19 | -1.33%
                Column ranges - without batch | 490.12 | 501.68 | +2.36%
                        Column ranges - batch | 124.27 | 125.01 | +0.60%

[sequba]

Instedy of button "copy as markdown" I'd prefer "view as markdown" on top of each documentation page. I think agent will more likely click a link and read the clipboard content and then navigate to it.

[marcin-kordas-hoc]

Done — the "copy as markdown" button is replaced by a "View as Markdown" link near the top of each guide page, linking to that page's .md companion.

[sequba]

I don't see the "View as Markdown" link near the top of each guide. @cursor fix it.

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

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

[GreenFlux]

@marcin-kordas-hoc , perhaps we should finish the docs migration to cloudflare first, and then use their markdown for agents feature, rather that write a custom vuepress->markdown script. We're already using this with the handsontable docs.
https://blog.cloudflare.com/markdown-for-agents/

Also, we plan to migrate the hyperformula docs to Atro, so the vuewpress->markdown script won't be needed after that either.
#1686

cc @qunabu @sequba

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.21%. Comparing base (23a7437) to head (f2e95fc).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1703   +/-   ##
========================================
  Coverage    97.21%   97.21%           
========================================
  Files          178      178           
  Lines        15611    15611           
  Branches      3460     3429   -31     
========================================
  Hits         15177    15177           
+ Misses         434      426    -8     
- Partials         0        8    +8     

see 5 files with indirect coverage changes

🚀 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.