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

.eslintrc.js

@@ -148,6 +148,24 @@ module.exports = {
       rules: {
         '@typescript-eslint/no-non-null-assertion': 'off',
       }
-    }
+    },
+    {
+      // Plain-Node Jest specs (e.g. docs tooling tests that `require` JS modules
+      // rather than importing typed sources).
+      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. [#1703](https://github.com/handsontable/hyperformula/pull/1703)
 - Added a new function: `XIRR`. [#1701](https://github.com/handsontable/hyperformula/pull/1701)
 - Added an Indonesian (Bahasa Indonesia) language pack. [#1674](https://github.com/handsontable/hyperformula/pull/1674)
 - Added a `stringifyCurrency` config option that lets you plug in a custom currency formatter for the `TEXT` function. [#1145](https://github.com/handsontable/hyperformula/issues/1145)

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", "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,93 @@
+<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>
+import { copyToClipboard } from './clipboard';
+
+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;
+      copyToClipboard(this.current.snippet).then(() => {
+        this.copied = true;
+        setTimeout(() => { this.copied = false; }, 1500);
+      });
+    },
+  },
+};
+</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,63 @@
+<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>
+import { copyToClipboard } from './clipboard';
+
+export default {
+  name: 'CopyMarkdownButton',
+  data() {
+    return { copied: false };
+  },
+  computed: {
+    mdUrl() {
+      const p = this.$page && this.$page.path;
+      // The 404 page is excluded from companion generation — no button there.
+      if (!p || p === '/404.html') return null;
+      // `.html` page → sibling `.md`; directory / landing URL (`/`, `/guide/`)
+      // → its `index.md` companion. Both are emitted by the md-companions plugin,
+      // so the button is available on every generated page.
+      if (/\.html$/.test(p)) return this.$withBase(p.replace(/\.html$/, '.md'));
+      if (p.endsWith('/')) return this.$withBase(`${p}index.md`);
+      return null;
+    },
+    label() {
+      return this.copied ? 'Copied!' : 'Copy Markdown link';
+    },
+  },
+  methods: {
+    copy() {
+      const absolute = window.location.origin + this.mdUrl;
+      copyToClipboard(absolute).then(() => {
+        this.copied = true;
+        setTimeout(() => { this.copied = false; }, 1500);
+      });
+    },
+  },
+};
+</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/components/clipboard.js

@@ -0,0 +1,29 @@
+/**
+ * Copy text to the clipboard, falling back to a hidden `<textarea>` +
+ * `execCommand('copy')` when the async Clipboard API is unavailable (insecure
+ * context / older browsers). Always resolves, so callers can chain a single
+ * `.then()` for their "Copied!" state regardless of which path ran.
+ *
+ * @param {string} text text to place on the clipboard
+ * @returns {Promise<void>}
+ */
+export function copyToClipboard(text) {
+  const fallback = () => {
+    // Never throw: the "always resolves" contract must hold even if the DOM
+    // or execCommand path fails (e.g. detached document, disabled command).
+    try {
+      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); }
+    } catch (_) { /* clipboard truly unavailable — nothing more we can do */ }
+  };
+  if (navigator.clipboard && window.isSecureContext) {
+    return navigator.clipboard.writeText(text).catch(fallback);
+  }
+  fallback();
+  return Promise.resolve();
+}

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,74 @@
+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 || '/';
+    // Include `.html` pages AND clean-URL / section-index pages whose path ends
+    // in `/` (home, directory landings) — otherwise they are silently absent
+    // from the corpus. Skip the 404 page (never a useful companion).
+    const pages = ctx.pages.filter(
+      p => (/\.html$/.test(p.path) || p.path.endsWith('/')) && p.path !== '/404.html'
+    );
+    const corpus = [
+      '# HyperFormula Documentation',
+      '',
+      '> Full documentation corpus for LLM consumption.',
+      '> Each page below is also served as clean Markdown — append `.md` to a docs page URL.',
+      '',
+    ];
+
+    for (const page of pages) {
+      try {
+        const clean = stripVuePressSyntax(page._strippedContent || '');
+        // `.html` → `<slug>.md`; directory URL (`/guide/`) → `<dir>/index.md`.
+        const relPath = page.path.endsWith('/')
+          ? `${page.path}index.md`
+          : 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}`);
+      }
+    }
+
+    // Best-effort like the per-page writes: a corpus-write failure warns rather
+    // than aborting the whole docs build.
+    const corpusText = corpus.join('\n');
+    try {
+      await fs.promises.writeFile(path.join(ctx.outDir, 'llms-full.txt'), corpusText, 'utf8');
+    } catch (err) {
+      console.warn(`[md-companions] failed to write llms-full.txt: ${err.message}`);
+    }
+
+    // The site is served under base `/docs/` (GH Pages in prod, Netlify preview),
+    // but the llms.txt convention expects the index at the domain ROOT. Mirror
+    // both files one level above the base dir (the served root) so `/llms.txt`
+    // and `/llms-full.txt` resolve on GH Pages — where netlify.toml redirects do
+    // not apply. Best-effort: never fail the build over the mirror.
+    try {
+      const root = path.dirname(ctx.outDir);
+      await fs.promises.writeFile(path.join(root, 'llms-full.txt'), corpusText, 'utf8');
+      const indexTxt = await fs.promises
+        .readFile(path.join(ctx.outDir, 'llms.txt'), 'utf8')
+        .catch(() => null);
+      if (indexTxt) await fs.promises.writeFile(path.join(root, 'llms.txt'), indexTxt, 'utf8');
+    } catch (err) {
+      console.warn(`[md-companions] failed to mirror llms files to site root: ${err.message}`);
+    }
+  }
+});