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

.eslintrc.js

@@ -148,6 +148,40 @@ module.exports = {
       rules: {
         '@typescript-eslint/no-non-null-assertion': 'off',
       }
-    }
+    },
+    {
+      files: ['scripts/*.js'],
+      env: {
+        node: true,
+      },
+      rules: {
+        '@typescript-eslint/no-var-requires': 'off',
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-call': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        '@typescript-eslint/no-unsafe-return': 'off',
+        '@typescript-eslint/restrict-template-expressions': 'off',
+        'no-undef': 'off',
+      },
+    },
+    {
+      // Plain-Node Jest specs (e.g. docs tooling tests that `require` JS modules
+      // rather than importing typed sources). Same relaxations as `scripts/*.js`.
+      files: ['**/test/**/*.spec.js'],
+      env: {
+        node: true,
+      },
+      rules: {
+        '@typescript-eslint/no-var-requires': 'off',
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-call': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        '@typescript-eslint/no-unsafe-return': 'off',
+        '@typescript-eslint/restrict-template-expressions': 'off',
+        'no-undef': 'off',
+      },
+    },
   ],
 }

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 
+- Added agent-friendly documentation: per-page `.md` companions, a Copy-Markdown button, an `llms.txt` index, and a coding-agent setup guide. [#1696](https://github.com/handsontable/hyperformula/pull/1696)
 - Added an Indonesian (Bahasa Indonesia) language pack. [#1674](https://github.com/handsontable/hyperformula/pull/1674)
 
 ## [3.3.0] - 2026-05-20

context7.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "HyperFormula",
+  "description": "Headless, Excel-compatible spreadsheet engine in TypeScript — parses and evaluates ~400 functions in the browser or Node.js. In-process library (no REST API).",
+  "folders": ["docs"],
+  "excludeFolders": ["docs/.vuepress/dist", "docs/api"],
+  "rules": [
+    "HyperFormula is an in-process library, not a REST API — there is no HTTP endpoint or base URL.",
+    "Public API cell addresses are 0-indexed: { sheet, col, row }.",
+    "There is no #CALC! error type.",
+    "EmptyValue is exported as a Symbol, not null/undefined.",
+    "A license key is required when constructing the engine (use 'gpl-v3' for open-source use)."
+  ]
+}

docs/.vuepress/components/CodingAgentWizard.vue

@@ -0,0 +1,104 @@
+<template>
+  <div class="agent-wizard">
+    <div v-if="!selected" class="agent-wizard__choices">
+      <p class="agent-wizard__prompt">Which coding agent do you use?</p>
+      <button
+        v-for="opt in options"
+        :key="opt.id"
+        class="agent-wizard__choice"
+        type="button"
+        @click="selected = opt.id"
+      >{{ opt.label }}</button>
+    </div>
+
+    <div v-else class="agent-wizard__result">
+      <button class="agent-wizard__back" type="button" @click="reset">&larr; Change</button>
+      <h3>{{ current.label }}</h3>
+      <pre class="agent-wizard__snippet"><code>{{ current.snippet }}</code></pre>
+      <button class="agent-wizard__copy" type="button" @click="copy">{{ copied ? 'Copied!' : 'Copy' }}</button>
+      <p class="agent-wizard__note" v-html="current.note"></p>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'CodingAgentWizard',
+  data() {
+    return {
+      selected: null,
+      copied: false,
+      options: [
+        {
+          id: 'claude-code',
+          label: 'Claude Code',
+          snippet: '/plugin marketplace add handsontable/handsontable-skills\n/plugin install handsontable-skills@handsontable-skills',
+          note: 'Installs the official <code>hyperformula</code> skill. Claude Code loads it automatically.',
+        },
+        {
+          id: 'cursor',
+          label: 'Cursor',
+          snippet: 'Add to your AGENTS.md / rules file:\nHyperFormula docs (LLM-friendly): https://hyperformula.handsontable.com/docs/llms-full.txt',
+          note: 'Cursor has no Claude-skill installer yet — point it at the full docs corpus instead.',
+        },
+        {
+          id: 'copilot',
+          label: 'GitHub Copilot',
+          snippet: 'Add to .github/copilot-instructions.md:\nReference HyperFormula docs: https://hyperformula.handsontable.com/docs/llms-full.txt',
+          note: 'Copilot reads an instructions file — link it to the corpus so it fetches authoritative docs.',
+        },
+        {
+          id: 'other',
+          label: 'Other / API',
+          snippet: 'curl -s https://hyperformula.handsontable.com/docs/llms-full.txt',
+          note: 'Fetch the full corpus, or upload the skill folder from <code>handsontable/handsontable-skills</code> to the Claude API.',
+        },
+      ],
+    };
+  },
+  computed: {
+    current() {
+      return this.options.find(o => o.id === this.selected) || null;
+    },
+  },
+  methods: {
+    reset() { this.selected = null; this.copied = false; },
+    copy() {
+      if (!this.current) return;
+      const text = this.current.snippet;
+      const fallback = (t) => {
+        const el = document.createElement('textarea');
+        el.value = t;
+        el.style.position = 'fixed';
+        el.style.opacity = '0';
+        document.body.appendChild(el);
+        el.select();
+        try { document.execCommand('copy'); } finally { document.body.removeChild(el); }
+      };
+      const done = () => { this.copied = true; setTimeout(() => { this.copied = false; }, 1500); };
+      if (navigator.clipboard && window.isSecureContext) {
+        navigator.clipboard.writeText(text).then(done).catch(() => { fallback(text); done(); });
+      } else {
+        fallback(text);
+        done();
+      }
+    },
+  },
+};
+</script>
+
+<style scoped>
+.agent-wizard { border: 1px solid #eaecef; border-radius: 6px; padding: 1rem 1.25rem; margin: 1.5rem 0; }
+.agent-wizard__prompt { font-weight: 600; margin: 0 0 0.75rem; }
+.agent-wizard__choice,
+.agent-wizard__copy,
+.agent-wizard__back {
+  cursor: pointer; border: 1px solid #3eaf7c; background: #fff; color: #3eaf7c;
+  border-radius: 4px; padding: 0.4rem 0.8rem; margin: 0 0.5rem 0.5rem 0; font-size: 0.9rem;
+}
+.agent-wizard__choice:hover,
+.agent-wizard__copy:hover { background: #3eaf7c; color: #fff; }
+.agent-wizard__back { border-color: #ccc; color: #666; }
+.agent-wizard__snippet { background: #f6f6f6; padding: 0.75rem; border-radius: 4px; overflow-x: auto; }
+.agent-wizard__note { font-size: 0.85rem; color: #666; }
+</style>

docs/.vuepress/components/CopyMarkdownButton.vue

@@ -0,0 +1,67 @@
+<template>
+  <button
+    v-if="mdUrl"
+    class="copy-md-button"
+    type="button"
+    :title="'Copy this page as Markdown URL for LLMs'"
+    @click="copy"
+  >{{ label }}</button>
+</template>
+
+<script>
+export default {
+  name: 'CopyMarkdownButton',
+  data() {
+    return { copied: false };
+  },
+  computed: {
+    mdUrl() {
+      const p = this.$page && this.$page.path;
+      if (!p || !/\.html$/.test(p)) return null;
+      return this.$withBase(p.replace(/\.html$/, '.md'));
+    },
+    label() {
+      return this.copied ? 'Copied!' : 'Copy Markdown';
+    },
+  },
+  methods: {
+    copy() {
+      const absolute = window.location.origin + this.mdUrl;
+      const fallback = (text) => {
+        const el = document.createElement('textarea');
+        el.value = text;
+        el.style.position = 'fixed';
+        el.style.opacity = '0';
+        document.body.appendChild(el);
+        el.select();
+        try { document.execCommand('copy'); } finally { document.body.removeChild(el); }
+      };
+      const done = () => { this.copied = true; setTimeout(() => { this.copied = false; }, 1500); };
+      if (navigator.clipboard && window.isSecureContext) {
+        navigator.clipboard.writeText(absolute).then(done).catch(() => { fallback(absolute); done(); });
+      } else {
+        fallback(absolute);
+        done();
+      }
+    },
+  },
+};
+</script>
+
+<style scoped>
+.copy-md-button {
+  position: fixed;
+  bottom: 1.5rem;
+  right: 1.5rem;
+  z-index: 100;
+  padding: 0.5rem 0.9rem;
+  font-size: 0.85rem;
+  border: 1px solid #3eaf7c;
+  border-radius: 4px;
+  background: #fff;
+  color: #3eaf7c;
+  cursor: pointer;
+  box-shadow: 0 1px 4px rgba(0,0,0,0.12);
+}
+.copy-md-button:hover { background: #3eaf7c; color: #fff; }
+</style>

docs/.vuepress/config.js

@@ -5,6 +5,7 @@ const searchBoxPlugin = require('./plugins/search-box');
 const examples = require('./plugins/examples/examples');
 const HyperFormula = require('../../dist/hyperformula.full');
 const includeCodeSnippet = require('./plugins/markdown-it-include-code-snippet');
+const mdCompanions = require('./plugins/md-companions');
 
 const searchPattern = new RegExp('^/api', 'i');
 
@@ -31,7 +32,7 @@ const DOCS_HOSTNAME = process.env.DOCS_HOSTNAME || buildConfigOverrides.hostname
 module.exports = {
   title: 'HyperFormula (v' + HyperFormula.version + ')',
   description: 'HyperFormula is an open-source, high-performance calculation engine for spreadsheets and web applications.',
-  globalUIComponents: [],
+  globalUIComponents: ['CopyMarkdownButton'],
   head: [
     // Import HF (required for the examples)
     [ 'script', { src: 'https://cdn.jsdelivr.net/npm/hyperformula/dist/hyperformula.full.min.js' } ],
@@ -89,6 +90,7 @@ module.exports = {
       exclude: ['/404.html'],
       changefreq: 'weekly'
     }],
+    [mdCompanions, { hostname: DOCS_HOSTNAME }],
     searchBoxPlugin,
     ['container', examples()],
     {
@@ -206,6 +208,7 @@ module.exports = {
             ['/guide/advanced-usage', 'Advanced usage'],
             ['/guide/configuration-options', 'Configuration options'],
             ['/guide/license-key', 'License key'],
+            ['/guide/setup-coding-agent', 'Set up your coding agent'],
           ]
         },
         {

docs/.vuepress/plugins/md-companions/index.js

@@ -0,0 +1,44 @@
+const fs = require('fs');
+const path = require('path');
+const { stripVuePressSyntax } = require('./strip');
+
+/**
+ * VuePress plugin: after build, write a clean `.md` companion next to each
+ * rendered `.html`, plus an aggregate `llms-full.txt`. Respects ctx.outDir
+ * (which already includes the configured base segment).
+ * @param {object} options plugin options
+ * @param {object} ctx VuePress app context
+ */
+module.exports = (options, ctx) => ({
+  name: 'md-companions',
+  async generated() {
+    const hostname = (options && options.hostname) || 'https://hyperformula.handsontable.com';
+    const base = ctx.base || '/';
+    const pages = ctx.pages.filter(p => /\.html$/.test(p.path) && p.path !== '/404.html');
+    const corpus = [
+      '# HyperFormula Documentation',
+      '',
+      '> Full documentation corpus for LLM consumption.',
+      `> Individual pages also available at ${hostname}${base}guide/<slug>.md`,
+      '',
+    ];
+
+    for (const page of pages) {
+      try {
+        const clean = stripVuePressSyntax(page._strippedContent || '');
+        const relPath = page.path.replace(/\.html$/, '.md');
+        const outFile = path.join(ctx.outDir, relPath.replace(/^\//, ''));
+        await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+        await fs.promises.writeFile(outFile, clean, 'utf8');
+
+        const url = hostname + base.replace(/\/$/, '') + page.path.replace(/\.html$/, '');
+        corpus.push('---', '', `## ${page.title || page.path}`, '', `URL: ${url}`, '', clean, '');
+      } catch (err) {
+        console.warn(`[md-companions] skipping ${page.path}: ${err.message}`);
+      }
+    }
+
+    const llmsFull = path.join(ctx.outDir, 'llms-full.txt');
+    await fs.promises.writeFile(llmsFull, corpus.join('\n'), 'utf8');
+  }
+});

docs/.vuepress/plugins/md-companions/strip.js

@@ -0,0 +1,75 @@
+/**
+ * Strips VuePress-specific markdown syntax, producing clean markdown
+ * suitable for LLM consumption. Fence-aware: never edits inside code blocks.
+ * @param {string} src raw markdown (frontmatter already removed)
+ * @returns {string} cleaned markdown
+ */
+function stripVuePressSyntax(src) {
+  const lines = src.split('\n');
+  const out = [];
+  let inFence = false;
+  let fenceMarker = '';
+  let inScript = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    const fenceMatch = trimmed.match(/^(```+|~~~+)/);
+    if (fenceMatch && !inScript) {
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = fenceMatch[1];   // full marker e.g. "```" or "````"
+      } else {
+        const closeMatch = trimmed.match(/^(```+|~~~+)/);
+        if (closeMatch && closeMatch[1][0] === fenceMarker[0] && closeMatch[1].length >= fenceMarker.length) {
+          inFence = false;
+        }
+      }
+      out.push(line);
+      continue;
+    }
+    if (inFence) {
+      out.push(line);
+      continue;
+    }
+
+    if (/^<(script|style)[\s>]/i.test(trimmed)) { inScript = true; continue; }
+    if (inScript) {
+      if (/<\/(script|style)>/i.test(trimmed)) inScript = false;
+      continue;
+    }
+
+    if (/^<[A-Z][A-Za-z0-9]*(\s[^>]*)?\/?>$/.test(trimmed)) continue;
+
+    if (/^\[\[toc\]\]$/i.test(trimmed)) continue;
+
+    const open = trimmed.match(/^:::\s*(\w+)\s*(.*)$/i);
+    if (open) {
+      const type = open[1].toLowerCase();
+      const title = open[2].trim();
+      const body = [];
+      i++;
+      const bodyStart = i;
+      while (i < lines.length && lines[i].trim() !== ':::') { body.push(lines[i]); i++; }
+      // If we hit EOF without finding closing :::, emit verbatim (not a real container).
+      if (i >= lines.length) {
+        out.push(lines[bodyStart - 1]); // re-emit the opening line
+        body.forEach(b => out.push(b));
+        continue;
+      }
+      // Demo/example containers (live code runners) are not prose — omit entirely.
+      if (type === 'example') { continue; }
+      if (title) { out.push(`> **${title}**`); out.push('>'); }
+      body.forEach(b => out.push(b.trim() === '' ? '>' : `> ${b}`));
+      while (out.length && out[out.length - 1] === '>') out.pop();
+      continue;
+    }
+
+    out.push(line);
+  }
+
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+module.exports = { stripVuePressSyntax };