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

.eslintrc.js

@@ -148,6 +148,6 @@ module.exports = {
       rules: {
         '@typescript-eslint/no-non-null-assertion': 'off',
       }
-    }
+    },
   ],
 }

DEV_DOCS.md

@@ -8,6 +8,7 @@ Canonical reference for everyone working on the HyperFormula source code: mainta
 - **[Test suite](test/README.md)** — smoke tests and how to attach the private test suite
 - **[Public docs portal](https://hyperformula.handsontable.com/docs)** — main documentation
 - **[Docs README](docs/README.md)** — how to run the docs portal locally
+- **[Docs content guide](DOCS_CONTENT_GUIDE.md)** — how to create and edit docs content
 - **[Changelog](CHANGELOG.md)**
 - **[Pull request template](.github/pull_request_template.md)**
 
@@ -90,6 +91,10 @@ A single pull request should contain an atomic self-contained functional change
 - All changes to the production code must be covered by automatic tests kept in the `test/` directory.
 - Each test case must be very simple and focused on a single assertion. Don't use loops, conditionals, or other control flow statements in test cases.
 
+## Documentation
+
+- Follow the [documentation content guide](DOCS_CONTENT_GUIDE.md) when creating or editing docs (writing style, language, and how to structure guides).
+
 ## How to add a new function
 
 Adding a built-in function is similar to adding a [custom function](docs/guide/custom-functions.md), so that guide is a useful reference for the function-implementation patterns (argument metadata, return types, array handling). The built-in flow on top of that is:

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,109 @@
+<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; }
+/* Match VuePress fenced code blocks ($codeBgColor = #282c34) so the snippet is
+   visually consistent with the rest of the docs' code blocks. */
+.agent-wizard__snippet {
+  background: #282c34;
+  color: #fff;
+  padding: 0.75rem 1rem;
+  border-radius: 6px;
+  overflow-x: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.agent-wizard__snippet code {
+  color: inherit;
+  background: transparent;
+  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New', monospace;
+  font-size: 0.85rem;
+}
+.agent-wizard__note { font-size: 0.85rem; color: #666; }
+</style>

docs/.vuepress/components/ViewMarkdownLink.vue

@@ -0,0 +1,72 @@
+<template>
+  <p v-if="mdUrl" class="view-markdown-link">
+    <a :href="mdUrl">View as Markdown</a>
+  </p>
+</template>
+
+<script>
+export default {
+  name: 'ViewMarkdownLink',
+  computed: {
+    mdUrl() {
+      const p = this.$page && this.$page.path;
+      // The 404 page is excluded from companion generation — no link 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 link 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;
+    },
+  },
+};
+</script>
+
+<style lang="stylus" scoped>
+@require '../styles/palette.styl'
+
+// Rendered in the `page-top` slot, this sits above `.theme-default-content`
+// at the very top of `main.page` — a zone the fixed navbar covers (the theme
+// clears the navbar only *inside* the content block, via the first heading's
+// top padding). Mirror the content wrapper's `$wrapper` geometry but take no
+// flow height: the link floats right-aligned inside the title's transparent
+// navbar-clearance padding, just above the page title, without pushing the
+// article down. `z-index` keeps it clickable above the heading's padding box.
+.view-markdown-link
+  position relative
+  z-index 1
+  max-width $contentWidth
+  height 0
+  margin 0 auto
+  padding 0 2.5rem
+  font-size 0.85rem
+
+  a
+    position absolute
+    top ($navbarHeight + 0.2rem)
+    right 2.5rem
+    line-height 1.4
+    color $accentColor
+    text-decoration none
+
+    &:hover
+      text-decoration underline
+
+// Keep the wrapper's paddings (and the anchor's `right` offset, resolved
+// against the wrapper's padding box) in lockstep with `$wrapper`'s responsive
+// paddings, so the link tracks the article text's right edge at every width.
+@media (max-width: $MQNarrow)
+  .view-markdown-link
+    padding 0 2rem
+
+    a
+      right 2rem
+
+@media (max-width: $MQMobileNarrow)
+  .view-markdown-link
+    padding 0 1.5rem
+
+    a
+      right 1.5rem
+</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,6 @@ 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: [],
   head: [
     // Import HF (required for the examples)
     [ 'script', { src: 'https://cdn.jsdelivr.net/npm/hyperformula/dist/hyperformula.full.min.js' } ],
@@ -89,6 +89,7 @@ module.exports = {
       exclude: ['/404.html'],
       changefreq: 'weekly'
     }],
+    [mdCompanions, { hostname: DOCS_HOSTNAME }],
     searchBoxPlugin,
     ['container', examples()],
     {
@@ -206,6 +207,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'],
           ]
         },
         {