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?

• Unit specs under test/docs/ (26 assertions, all passing): md-companions-strip.spec.js covers the stripper's transforms and edge cases; md-companions-generated.spec.js covers the generated() hook (per-page writes, root mirror, per-page error isolation, empty content, URL/base construction) with fs stubbed. Both are .js Jest specs (Karma globs only .spec.ts, so they stay out of the browser bundle).
• npm run lint clean (an ESLint override for **/test/**/*.spec.js allows the plain-Node specs).
• The full corpus was sanity-checked against the Netlify deploy-preview build (llms-full.txt populated, per-page .md clean, no leaked components).

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
Changes are confined to documentation, VuePress build plugins, and Netlify Node version; no production engine or runtime API behavior is modified.

Overview
Adds machine-readable documentation on top of the existing VuePress site: a build-time md-companions plugin strips VuePress-only syntax and writes a .md companion beside each HTML page, plus llms-full.txt (all pages in one file with absolute links). Root-relative links are rebased for /docs/; companions are mirrored one level above the output dir for GitHub Pages. A static llms.txt index and context7.json help external doc tools discover the corpus.

UX and navigation: a local theme injects View as Markdown on every page; a new Set up your coding agent guide (sidebar entry) documents skills, llms-full.txt, GitMCP, and Context7, with an interactive CodingAgentWizard and shared clipboard helper.

Authoring: new DOCS_CONTENT_GUIDE.md and links from DEV_DOCS.md / docs/README.md describe RAG-friendly writing. netlify.toml bumps Node to 22 and documents why domain-root llms redirects are intentionally omitted.

^{Reviewed by Cursor Bugbot for commit ebf978d. 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	ebf978d
🔍 Latest deploy log	https://app.netlify.com/projects/hyperformula-dev-docs/deploys/6a5b9898274cf00008f3f1d8
😎 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 (ebf978d) vs base (fd04f77)

                                     testName |    base |   head | change
-------------------------------------------------------------------------
                                      Sheet A |  487.05 | 494.84 | +1.60%
                                      Sheet B |  152.39 | 154.56 | +1.42%
                                      Sheet T |  138.51 |  139.4 | +0.64%
                                Column ranges |  460.54 | 463.52 | +0.65%
                                Sorted lookup | 13950.9 |  14330 | +2.72%
Sheet A:  change value, add/remove row/column |   15.29 |  15.29 |  0.00%
 Sheet B: change value, add/remove row/column |  127.03 | 130.47 | +2.71%
                   Column ranges - add column |  145.97 | 148.37 | +1.64%
                Column ranges - without batch |  435.58 | 441.82 | +1.43%
                        Column ranges - batch |  110.67 |  111.1 | +0.39%

[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 ebf978d. Configure here.}

[cursor]

Root mirror still claims paths

Medium Severity

After the build, md-companions still writes llms.txt and llms-full.txt one level above ctx.outDir, so with dest at docs/.vuepress/dist/docs and publish at docs/.vuepress/dist those files are served at the domain root. That conflicts with this PR’s own netlify.toml guidance that the docs site must not claim /llms.txt / /llms-full.txt and should leave the root corpus alone.

Additional Locations (1)

• netlify.toml#L7-L12

 

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.17%. Comparing base (fd04f77) to head (ebf978d).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1703   +/-   ##
========================================
  Coverage    97.17%   97.17%           
========================================
  Files          176      176           
  Lines        15483    15483           
  Branches      3429     3429           
========================================
  Hits         15045    15045           
  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.