Clean up in-repo dev docs (HF-65) (#1682)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
### Context

The in-repo developer documentation was scattered across several files
with significant duplication:

- `CLAUDE.md` duplicated build/test commands (also in
`docs/guide/building.md`), contributing rules (also in `CONTRIBUTING.md`
/ `docs/guide/contributing.md`), and translation sources (also in
`DEV_DOCS.md`).
- `CONTRIBUTING.md` was an almost-verbatim copy of
`docs/guide/contributing.md`.
- `DEV_DOCS.md` contained only a small subset of what a developer needs.
- Cursor-specific guidance did not exist.

This PR removes the duplication and gives both humans and AI agents a
single, predictable entry point.

### New structure

| File | Role |
| --- | --- |
| `DEV_DOCS.md` | **Canonical** dev docs. Project overview,
architecture, code style, definition of done, how to add a function,
translation sources, plus quick links to the build / contributing / test
docs. |
| `docs/guide/building.md` | Full description of build, verify, docs,
test, and lint commands, including output formats. Public, for users and
devs. |
| `docs/guide/contributing.md` | Full contributor guide. Public, for
users and devs. |
| `AGENTS.md` | Pointer to `DEV_DOCS.md` plus rules specific to AI
agents (attribution, response style). |
| `CLAUDE.md` | Pointer to `AGENTS.md`. |
| `.cursor/rules/main.mdc` | Cursor rule that points to `AGENTS.md`
(always applied). |
| `CONTRIBUTING.md` | Pointer to `docs/guide/contributing.md`. |

### How did you test your changes?

Manual review of the resulting file set:

- `DEV_DOCS.md` contains everything a developer needs and links to
`docs/guide/building.md`, `docs/guide/contributing.md`,
`docs/guide/code-of-conduct.md`, `test/README.md`, `docs/README.md`,
`CHANGELOG.md`, and `.github/pull_request_template.md`.
- `AGENTS.md` links to `DEV_DOCS.md` and only adds agent-specific rules.
- `CLAUDE.md`, `.cursor/rules/main.mdc`, and `CONTRIBUTING.md` are thin
pointers with no duplicated content.
- `docs/guide/building.md` is the only place that lists build/test/lint
commands and bundle output formats.
- `docs/guide/contributing.md` is unchanged (it already covered the
contributor flow in full).

### Types of changes

- [ ] Breaking change (a fix or a feature because of which an existing
functionality doesn't work as expected anymore)
- [ ] New feature or improvement (a non-breaking change that adds
functionality)
- [ ] Bug fix (a non-breaking change that fixes an issue)
- [ ] Additional language file, or a change to an existing language file
(translations)
- [x] Change to the documentation

### Related issues

1. HF-65

### Checklist

- [x] I have reviewed the guidelines about [Contributing to
HyperFormula](https://hyperformula.handsontable.com/guide/contributing.html)
and I confirm that my code follows the code style of this project.
- [ ] I have signed the [Contributor License
Agreement](https://goo.gl/forms/yuutGuN0RjsikVpM2).
- [ ] My change is compliant with the
[OpenDocument](https://docs.oasis-open.org/office/OpenDocument/v1.3/os/part4-formula/OpenDocument-v1.3-os-part4-formula.html)
standard.
- [ ] My change is compatible with Microsoft Excel.
- [ ] My change is compatible with Google Sheets.
- [ ] I described my changes in the
[CHANGELOG.md](https://github.com/handsontable/hyperformula/blob/master/CHANGELOG.md)
file.
- [ ] My changes require a documentation update.
- [ ] My changes require a migration guide.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-0a7bf4d1-d3c8-4edd-aacd-3a9df3a69526"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-0a7bf4d1-d3c8-4edd-aacd-3a9df3a69526"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Kuba Sekowski <sequba@users.noreply.github.com>
Co-authored-by: marcin-kordas-hoc <marcin.kordas@handsontable.com>

Author: 3 people

.cursor/rules/main.mdc

@@ -0,0 +1,6 @@
+---
+description: Project-wide guidance for AI agents working in this repository
+alwaysApply: true
+---
+
+All guidance for AI agents working in this repository lives in [AGENTS.md](mdc:AGENTS.md) at the repository root. Read it first.

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+Instructions for AI coding agents (Cursor, Claude Code, Codex, Aider, and any other AI tool) working in this repository.
+
+## Start here
+
+Whatever you do, start by reading entire [DEV_DOCS.md](DEV_DOCS.md). Only then proceed to your task.
+
+## Other important resources
+
+- the repository [README.md](README.md) — high-level project description and quick install/usage
+- the markdown files in [`docs/guide/`](docs/guide/) — user-facing guides (installation, configuration, built-in functions, custom functions, integrations, etc.)
+- the markdown files in [`docs/api/`](docs/api/) — API reference (generated from JSDoc; run `npm run docs:build` if the folder is missing)
+
+Prefer reading these local files over fetching the rendered documentation from the web.
+
+## Response style
+
+- Be concise by default. Use as few words as possible unless the user asks for more detail.
+- When the user asks for specific content, lead the response with the requested information.
+- Structure answers with bullet lists, numbered lists, tables, or code blocks where useful.
+- Ask clarifying questions when the request is ambiguous rather than guessing.
+- If you do not know something, say so and ask for help.
+- When answering from project documentation, quote the exact relevant fragments to support your claim.
+
+## Common ways agents fail
+
+This section is maintained by the team. Whenever an AI agent makes a mistake worth flagging, an item is added here describing what the agent did wrong and what it should have done instead. Read this list before starting any non-trivial task.
+
+<!-- Add new items to the top of the list. Use the format:
+- **Short title** &mdash; What the agent did wrong. What it should have done instead.
+-->
+
+_No items yet._
+
+## Skills, MCPs, and other agent tools
+
+This section is maintained by the team. Skills, MCP servers, and other tools vetted as useful for AI agents working on this codebase are listed here.
+
+<!-- Add new items here. Use the format:
+- **Name** &mdash; What it provides and when to use it.
+-->
+
+_No items yet._

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CLAUDE.md

@@ -0,0 +1 @@
+docs/guide/contributing.md

CONTRIBUTING.md

@@ -1,27 +1,104 @@
-# Dev Docs
+# Developer documentation
 
-Random notes and things to know useful for maintainers and contributors.
+Canonical reference for everyone working on the HyperFormula source code: maintainers, the internal team, and AI agents triggered by them. Everything a developer needs to know lives here or is linked from here.
 
-## Definition of Done for the code changes
+## Quick links
 
-Each change to the production code (bugfixes, new features, improvements) must include these elements. They must be present in the pull request BEFORE requesting the code review.
+- **[Building, testing, and linting](docs/guide/building.md)** — all `npm` commands and build outputs
+- **[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
+- **[Changelog](CHANGELOG.md)**
+- **[Pull request template](.github/pull_request_template.md)**
 
-- changes to the production code
-  - including changes to all supported language packs in `src/i18n/languages` directory (if applicable)
-- automatic tests
-  - for bugfixes: at least one test reproducing the bug
-  - for new features: a set of tests describing the feature specification precisely
-  - pull requests from external contributors should include tests in `tests/` directory (they will be moved to the private repository by the internal team)
-  - internal team adds tests directly to the private repository (through a separate pull request)
-- updates to documentation related to the change
+## Repository layout
+
+```
+.
+├── src/                        # Source code
+│   ├── HyperFormula.ts         # Main engine class, public API entry point
+│   ├── parser/                 # Formula parsing (uses Chevrotain parser generator)
+│   ├── interpreter/            # Formula evaluation engine
+│   │   └── plugin/             # Built-in spreadsheet function plugins
+│   ├── DependencyGraph/        # Cell dependency tracking and recalculation order
+│   ├── CrudOperations.ts       # Create/read/update/delete operations on sheets and cells
+│   └── i18n/                   # Function-name translations per language
+├── test/                       # Test suite
+├── docs/                       # Public documentation portal (VuePress)
+│   ├── guide/                  # Markdown guides (building, contributing, usage…)
+│   ├── api/                    # API reference (generated from JSDoc)
+│   ├── .vuepress/              # VuePress configuration, theme, components
+│   └── README.md               # How to run the docs portal locally
+├── script/                     # Maintenance and release scripts
+├── .github/                    # CI workflows, issue and PR templates
+├── DEV_DOCS.md                 # Canonical developer documentation (this file)
+├── AGENTS.md                   # Guidance for AI agents
+├── CONTRIBUTING.md             # Guide for external contributors
+├── README.md                   # Project overview
+├── CHANGELOG.md
+├── LICENSE.txt
+├── package.json
+└── tsconfig.json
+```
+
+## Architecture
+
+### Core modules
+
+- `src/HyperFormula.ts` — main engine class, public API entry point
+- `src/parser/` — formula parsing (uses the [Chevrotain](https://chevrotain.io/) parser generator)
+- `src/interpreter/` — formula evaluation engine
+- `src/DependencyGraph/` — cell dependency tracking and recalculation order
+- `src/CrudOperations.ts` — create/read/update/delete operations on sheets and cells
+
+### Function plugins (`src/interpreter/plugin/`)
+
+All spreadsheet functions are implemented as plugins extending `FunctionPlugin`. Each plugin:
+
+- declares an `implementedFunctions` static property mapping function names to metadata
+- uses the `runFunction()` helper for argument validation, coercion, and array handling
+- registers function translations in `src/i18n/languages/`
+
+## 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:
+
+1. Create or modify a plugin in `src/interpreter/plugin/`.
+2. Add function metadata to `implementedFunctions`.
+3. Implement the function method.
+4. Add translations to all language files in `src/i18n/languages/`.
+5. Add tests in `test/unit/interpreter/`.
+
+## Code style
+
+- Prefer a functional approach where possible (`filter`, `map`, `reduce`).
+- Write self-documenting code: use meaningful names for classes, functions, and variables. Add code comments only when they explain intent the code itself cannot.
+- Add JSDoc to all classes and functions.
+- ESLint is the source of truth for formatting and code rules. Run `npm run lint` before submitting changes (see [building](docs/guide/building.md#run-the-linter)).
+
+## Definition of Done
+
+Each change to the production code (bugfix, new feature, or improvement) must include the following elements **before** requesting a code review:
+
+- Changes to the production code
+  - including changes to all supported language packs in `src/i18n/languages` (if applicable)
+- Automatic tests
+  - for bug fixes: at least one test reproducing the bug
+  - for new features: a set of tests precisely describing the feature
+  - pull requests from external contributors should include tests in the `test/` directory (they will be moved to the private repository by the internal team)
+  - the internal team adds tests directly to the private repository (through a separate pull request)
+- Updates to documentation related to the change
   - for breaking changes: a section in the migration guide
-- technical documentation in the form of the jsdoc comments (high-level description of the concepts used in the more complex code fragments)
-- changelog entry
-- pull request description
+- Technical documentation in the form of JSDoc comments (high-level description of the concepts used in more complex code fragments)
+- Changelog entry
+- Pull request description
+
+## Internationalization and function translations
+
+HyperFormula supports internationalization and provides localized function names for all built-in languages. Translation files live in `src/i18n/languages/`. New functions must include translations for all built-in languages.
 
-## Sources of the function translations
+When looking for the valid translations for new functions, try these sources:
 
-HF supports internationalization and provides the localized function names for all built-in languages. When looking for the valid translations for the new functions, try these sources:
 - https://support.microsoft.com/en-us/office/excel-functions-translator-f262d0c0-991c-485b-89b6-32cc8d326889
 - http://dolf.trieschnigg.nl/excel/index.php
 

CONTRIBUTING.md

@@ -4,6 +4,21 @@ The build process uses Webpack and Babel, as well as npm tasks
 listed in package.json. During this process, the source located in
 the `src/*` directory is transformed into the output files.
 
+The library is developed in TypeScript and the exact configuration
+options can be found in `tsconfig.json`. To run the commands you need
+to set up your environment to have `npm` or `yarn` properly installed.
+After that, navigate to the project and run `npm install`.
+
+## Output formats
+
+The build produces the following output formats, all declared as
+entry points in `package.json`:
+
+* `commonjs/` - CommonJS modules (main entry, used by Node.js and bundlers)
+* `es/` - ES modules (`.mjs` files, used by tree-shaking bundlers)
+* `dist/` - UMD bundles for direct use in the browser
+* `typings/` - TypeScript declaration files (`.d.ts`)
+
 **For UMD versions which reside in CDN:**
 
 * `./dist/hyperformula.js` - a full version which does not have
@@ -14,16 +29,6 @@ have  dependencies, they need to be added manually
 * `./dist/hyperformula.full.min.js` - a minified version with
 dependencies
 
-There are also versions of builds in CommonJS, ES6, and TypeScript
-definitions. They are marked in the package.json file. Based on
-the tools used (Webpack, parsers, etc.), a proper build will be
-respectively chosen.
-
-The library is developed in TypeScript and the exact configuration
-options can be found in `tsconfig.json`. To run the commands you need
-to set up your environment to have `npm` or `yarn` properly installed.
-After that, navigate to the project and run `npm install`.
-
 ## Build the project
 
 To build the project you can use the following commands: