chore(release): 7.14.0 [skip ci]

# [7.14.0](https://git.datacontroller.io/dc/dc/compare/v7.13.0...v7.14.0) (2026-09-04)

### Features

* **system:** show session timezone on system information screen ([966dc07](966dc072e0))

.agents/docs/bitemporal-dataloader.md

@@ -0,0 +1,147 @@
+# Bitemporal Dataloader — Technical Deep Dive
+
+This document explains how the Data Controller backend loads staged data into target tables: the load-type dispatch, the internals of the `%bitemporal_dataloader` macro, and a detailed description of the REPLACE load type. For user-facing load type documentation, see [docs.datacontroller.io](https://docs.datacontroller.io/).
+
+## Overview
+
+Every table registered for loading has a current record in `&mpelib..MPE_TABLES` with a `LOADTYPE` (selectbox values are seeded in `mpe_makedata.sas`):
+
+| LOADTYPE | Loader used | History kept |
+|---|---|---|
+| `UPDATE` | `%bitemporal_dataloader` (no temporal vars) | None — changed records are deleted and re-appended |
+| `REPLACE` | Inline code in `%mpe_targetloader` (does **not** use `%bitemporal_dataloader`) | None — entire table wiped and reloaded |
+| `TXTEMPORAL` | `%bitemporal_dataloader` (technical time only) | SCD2-style, technical (transaction) time |
+| `BITEMPORAL` | `%bitemporal_dataloader` (business + technical time) | Full two-dimensional history |
+| `FORMAT_CAT` | `%mp_loadformat` | Format catalog load (table suffix `-FC`) |
+
+The relevant `MPE_TABLES` columns read by the loader are: `LOADTYPE`, `BUSKEY` (primary key, space-separated, excluding temporal columns), `VAR_TXFROM` / `VAR_TXTO` (technical validity), `VAR_BUSFROM` / `VAR_BUSTO` (business validity), `VAR_PROCESSED` (processed timestamp column), `RK_UNDERLYING` (retained-key generation), `CLOSE_VARS`, and `AUDIT_LIBDS` (defaults to `&dclib..MPE_AUDIT`).
+
+## Request Flow
+
+```mermaid
+flowchart TD
+    A[User submits changeset\neditors/stagedata.sas] --> B[Staging package written to\n&mpelocapprovals/&LOAD_REF\nCSV + jsdata]
+    B --> C[Approval workflow\nMPE_SUBMIT / MPE_REVIEW]
+    C --> D{auditors/postdata.sas}
+    D -->|action=SHOW_DIFFS| E["%mpe_targetloader(LOADTARGET=NO)\nbuilds work.outds_add / outds_mod / outds_del\nfor the diff screen only"]
+    D -->|action=APPROVE_TABLE| F["%mpe_targetloader(LOADTARGET=YES)\nactual load"]
+    E --> G[Diff CSV + TEMPDIFFS stored\nin approval package]
+    F --> H{LOADTYPE from\nMPE_TABLES}
+    H -->|UPDATE / TXTEMPORAL / BITEMPORAL| I["%bitemporal_dataloader"]
+    H -->|FORMAT_CAT| J["%mp_loadformat"]
+    H -->|REPLACE| K[Inline delete-all + append\nin %mpe_targetloader]
+```
+
+`%mpe_targetloader` (`sas/sasjs/macros/mpe_targetloader.sas`) is the single dispatch point. It reads the current `MPE_TABLES` record (`&dc_dttmtfmt. lt tx_to`), aborts if the table is not registered (or has duplicate config records), and routes to the loader. Note the two-phase design: `LOADTARGET=NO` prepares the intermediate `outds_*` tables so the approver can review diffs; `LOADTARGET=YES` performs the destructive load. Both phases run the same preparation logic, so the reviewed diffs correspond to what is actually applied.
+
+## The Temporal Model
+
+Bitemporal tables carry two independent time dimensions:
+
+* **Business time** (`bus_from` / `bus_to`) — when the fact was true in the real world. Present on **both** staging and base tables.
+* **Technical time** (`tech_from` / `tech_to`, a.k.a. transaction time) — when the record was known to the database. Present on the **base table only**; the loader stamps these itself.
+
+All validity is expressed with **half-open intervals** (`from <= t < to`). Queries against bitemporal tables need two conditions and must not use `BETWEEN` or `from LE t LE to` (the latter excludes boundary records — see the macro header for background):
+
+```sas
+where &bus_from le [tstamp] lt &bus_to
+  and &tx_from le [tstamp] lt &tx_to
+```
+
+"Current" records have `tech_to` set to the high date (`'31DEC9999:23:59:59'dt` when called from `%mpe_targetloader`). Closing out a record means setting `tech_to = now` — records are never physically deleted from a temporal table, they are superseded.
+
+## Key Components
+
+| Component | Location | Role |
+|---|---|---|
+| `%mpe_targetloader` | `sas/sasjs/macros/mpe_targetloader.sas` | Reads `MPE_TABLES` config and dispatches per LOADTYPE; implements REPLACE inline |
+| `%bitemporal_dataloader` | `sas/sasjs/macros/bitemporal_dataloader.sas` | Generic loader for UPDATE / TXTEMPORAL / BITEMPORAL |
+| `%bitemporal_closeouts` | `sas/sasjs/macros/bitemporal_closeouts.sas` | Closes out (sets `tech_to=now`) live records matching a key |
+| `%mp_retainedkey` | SASjs core | Generates retained (surrogate) keys when `RK_UNDERLYING` is configured |
+| `%mp_rowhash` | SASjs core | MD5 hash of non-temporal columns, used for change detection |
+| `%mp_storediffs` | SASjs core | Writes row-level audit records to `AUDIT_LIBDS` |
+| `MPE_DATALOADS` | `&dclib` | Load log (counts, duration, macro version, user) — written only by `%bitemporal_dataloader` |
+| `MPE_LOCKANYTABLE` | `&dclib` | Lock control table used by `%mp_lockanytable` |
+
+## `%bitemporal_dataloader` Execution Flow
+
+The macro builds a series of `work.bitemp*` intermediate tables, then applies the changes in two target-table operations (closeout, then append) under a single lock.
+
+### 1. Pre-checks and setup
+
+* Early return if the staging table is empty; hard abort if `&syscc > 0`.
+* `CLOSE_VARS` is not supported on REDSHIFT / POSTGRES / SNOWFLAKE engines (returns with a NOTE).
+* A zero-row snapshot of the base table (`&basecopy`) is taken with `data ... set base; stop;` — this doubles as a lock check, since metadata functions fail against a locked table.
+* `proc contents` on the base table feeds column lists. Columns are split into character and numeric lists for hashing (`%mp_rowhash` hashes the two types via separate arrays). Temporal columns, the processed column, and the delete-flag column are excluded from the hash.
+* Table names containing `___TMP___` or `_____` are rejected (they would collide with generated temp columns).
+
+### 2. Locking
+
+For `LOADTARGET=YES`, the base table (and audit table, if configured) is locked via `%mp_lockanytable` before any staging prep, because the load is a two-part update (closeouts + append) and must not interleave with another load.
+
+### 3. Staging preparation (`work.bitemp0_append`)
+
+* If `RK_UNDERLYING` is configured, `%mp_retainedkey` maps business keys to retained keys (filtering the base lookup to live records, `&now < tech_to`, for temporal types); otherwise the staging table is used as-is.
+* `bus_from` / `bus_to` overrides are applied if provided; the processed column is stamped with the load timestamp (`now`). Even with `processed=0`, a column literally named `PROCESSED_DTTM` on the base table is used if present.
+* The MD5 change-detection hash is computed for every staged record.
+* If the staging table contains the delete-flag column (`_____DELETE__THIS__RECORD_____`), rows flagged `"Yes"` are diverted to `&outds_del` and closed out via `%bitemporal_closeouts` (PK is taken as `bus_from` + business key). The remaining rows continue as `bitemp0_append`.
+
+### 4. CLOSE_VARS closeout
+
+When `CLOSE_VARS` (a subset of the PK) is supplied, live base records whose CLOSE_VARS values appear in staging but whose full PK does **not** are closed out. This handles "this group was fully reloaded, so anything missing was removed" semantics without reloading the whole table.
+
+### 5. Uniqueness check
+
+If `CHECK_UNIQUENESS=YES` (the default) or business-date overrides are in play, the staging table is sorted `nodupkey` by the PK; a row-count mismatch aborts the load and releases the locks. The staging table must be a unique snapshot of the business key at one point in business time.
+
+### 6. Base extract (`work.bitemp0_base`)
+
+Only base records matching staged PKs are extracted — for temporal load types, only **currently live** records (`now < tech_to`). A left join from the staged keys to the base produces `___TMP___NEW_FLG` to identify brand-new keys. This is engine-specific:
+
+* **OLEDB (SQL Server)** — staged keys are pushed to a `##global` temp table and joined via explicit pass-through.
+* **REDSHIFT / POSTGRES / SNOWFLAKE** — an in-database temp table is created `like` the base, stripped to PK + an added `md5 varchar(32)` column, loaded with staged keys, and joined via pass-through. Snowflake uses transient tables; Redshift gets `alter sortkey none` plus any `DCBL_REDSH` config options from `MPE_CONFIG`.
+* **CAS** — a FedSQL join against a CASUSER copy.
+* **BASE/other** — plain PROC SQL in SAS.
+
+### 7. Change classification
+
+* **`&outds_add`** — staged records flagged as new (no base match). They get `tech_from=now`, `tech_to=high_date`.
+* **`work.bitemp1_current`** — matched base records, re-hashed so hashes are comparable.
+* **Inserts (BITEMPORAL only)** — a staged record whose business range falls strictly *inside* an existing record's range splits the existing record into a "before" and "after" segment (`bitemp3_inserts` / `bitemp3a_inserts`). The split segments replace the original in the comparison set (`bitemp3b_newbase`).
+* **Updates (`bitemp4*`)** — staged records matching a base PK but with a different hash or different business dates. Base and staged versions are stacked, deduplicated, then aligned in **two passes** over the business timeline per key: a forward pass (carry `bus_from` forward across identical hashes; a staged record trims the preceding base record's range) and a reverse pass (carry `bus_to` back; records fully subsumed by the new version are deleted). Records that end up byte-identical to what is already stored are dropped via a hash lookup that includes the business dates (`bitemp5a_lkp` / `bitemp5b_updates`, BITEMPORAL only).
+
+### 8. Closeout application
+
+Changed records are closed out in the target before the new versions are appended. SAS SQL has no UPDATE-with-join, so a correlated `EXISTS` subquery against `work.bitemp5d_subquery` is used (pushed in-database as a temp table for OLEDB / REDSHIFT / POSTGRES / SNOWFLAKE):
+
+* **BITEMPORAL** — per key, the closeout range is `min(bus_from)` / `max(bus_to)` of the changed records: `update base set tech_to=now (, processed=now) where tech_from <= now < tech_to and exists (key match and base.bus_from >= min and base.bus_to <= max)`.
+* **TXTEMPORAL** — same, on key only.
+* **UPDATE** — changed records are physically `delete`d (they are re-appended in the next step). On CAS this uses `table.deleteRows` with a whereTable; temporal types are not supported on CAS and abort.
+* **BUSTEMPORAL** — closeouts are not implemented; the macro aborts at this point ("BUSTEMPORAL NOT YET SUPPORTED").
+
+### 9. Append, unlock, audit, log
+
+* The union of modified + new records, deduplicated on all columns (`bitemp6_unique`), is appended to the base table (`proc append ... force nowarn`; CAS appends via a varchar-casting step; Redshift applies `DCBL_REDSH` options). Locks are then released.
+* If `outds_audit` is set (always, from `%mpe_targetloader` — `AUDIT_LIBDS` defaulting to `&dclib..MPE_AUDIT`), `%mp_storediffs` compares the pre-load snapshot with the applied changes and appends row-level audit records; modified-row entries with no actual value change are removed (`MOVE_TYPE="M" and IS_PK=0 and IS_DIFF=0`).
+* A summary row is inserted into `&dclib..MPE_DATALOADS` (libref, dsn, etlsource, loadtype, changed/new/deleted counts, duration, macro version, user, timestamp) unless `LOG=0`.
+
+## REPLACE Load Type
+
+REPLACE is the simplest load type and is deliberately **not** routed through `%bitemporal_dataloader` — it is implemented inline in `%mpe_targetloader` and simply wipes the target table (`delete * from`) and re-appends the staging table verbatim, with no history, change detection, key matching, audit rows, or `MPE_DATALOADS` logging. See [replace-load-type.md](replace-load-type.md) for the full deep dive.
+
+## Supporting Tables
+
+| Table | Role |
+|---|---|
+| `MPE_TABLES` | Per-table load configuration (loadtype, keys, temporal vars, audit target) |
+| `MPE_SELECTBOX` | Dropdown values, including the LOADTYPE list (seeded in `mpe_makedata.sas`) |
+| `MPE_SUBMIT` / `MPE_REVIEW` | Approval workflow state |
+| `MPE_LOADS` | Submission-level log of CSV package loads |
+| `MPE_DATALOADS` | Per-load statistics (temporal/UPDATE loads only) |
+| `MPE_AUDIT` (or `AUDIT_LIBDS`) | Row-level change audit (temporal/UPDATE/FORMAT_CAT loads only) |
+| `MPE_LOCKANYTABLE` | Lock control table |
+| `MPE_CONFIG` | Engine-specific config (e.g. `DCBL_REDSH` scope for Redshift bulk options) |
+
+## Testing
+
+Unit tests for the loaders live next to the macros: `sas/sasjs/macros/bitemporal_dataloader.test.[1-4].sas` and `sas/sasjs/macros/mpe_targetloader.test.sas` (REPLACE loadtype), executed as sasjs tests. See [testing.md](testing.md) for how to run them (`npm run 4gl` then `sasjs test -t 4gl` from the `sas/` directory), and remember `sasjs lint` after touching any `.sas` files.

.agents/docs/dependency-updates.md

@@ -0,0 +1,19 @@
+# Dependency Updates Checklist
+
+Whenever any `package.json` (root, `client/`, or `sas/`) or lockfile is modified, run the same checks CI runs before pushing:
+
+1. **npm audit** (must be clean for prod deps):
+   ```bash
+   npm audit --omit=dev            # in repo root
+   cd sas && npm audit --omit=dev
+   cd ../client && npm audit --omit=dev
+   ```
+   Fix with `npm audit fix`, targeted `overrides` in `package.json`, or version bumps — never `npm audit fix --force` blindly, as it can introduce breaking changes.
+
+2. **License checker** (client only):
+   ```bash
+   cd client && npm run license-checker
+   ```
+   If a new dependency fails, either add its SPDX id to the `onlyAllow` list in `client/licenseChecker.js` (if the license is acceptable, e.g. permissive ones like `BlueOak-1.0.0`) or add the specific package to `excludePackages` with justification. Data Controller ships on-prem, so only OSI-approved permissive licenses are acceptable for production dependencies.
+
+Both checks run in `.gitea/workflows/build.yaml` (`Check audit` and `Licence checker` steps) and will fail the build if skipped locally.

.agents/docs/regex-validations.md

@@ -0,0 +1,86 @@
+# Regex Validations (HARDREGEX / SOFTREGEX)
+
+This document describes how the regex validation rules work internally. For user-facing documentation see `docs/dcc-validations.md` in the `docs.datacontroller.io` repo.
+
+## Overview
+
+Two validation rule types in `MPE_VALIDATIONS` validate cell values against a regular expression supplied in `RULE_VALUE`:
+
+- `HARDREGEX` - submission-blocking. A failing value is rejected by the cell validator and painted red (HOT's own `htInvalid` class), so the row cannot be submitted.
+- `SOFTREGEX` - display-only warning. A failing value is painted yellow (`dc-warning-cell` class) with a tooltip, but submission is not blocked.
+
+Both rule types are selectable in the MPE_VALIDATIONS RULE_TYPE dropdown; they were added to the selectbox seed data in `sas/sasjs/macros/mpe_makedata.sas` and via the optional migration `sas/sasjs/db/migrations/20260720_v7.12_release.sas`. `RULE_VALUE` is limited to 128 characters, which constrains very long patterns.
+
+## Config-time validation (SAS side)
+
+`sas/sasjs/services/hooks/mpe_validations_postedit.sas` runs `prxparse()` on any staged HARDREGEX/SOFTREGEX rule value and aborts the edit with a list of offending `libref.table.column` references if the pattern is invalid. This is a best-effort syntax check to catch typos at config time; an empty pattern is treated as valid (it matches everything in JS). Rows marked for delete are skipped.
+
+Because patterns must pass `prxparse`, rule values are authored in the SAS PRX delimiter form `/pattern/flags` (although a bare pattern is also accepted for backwards compatibility).
+
+## Frontend evaluation
+
+All regex handling lives in the client; there is no server-side re-validation of data values.  The per-cell decision flow:
+
+```mermaid
+flowchart TD
+    A[Cell value] --> B{Row marked for delete<br/>and not a PK column?}
+    B -- Yes --> Z[No validation / no warning]
+    B -- No --> C{isRegexRuleExempt?<br/>blank, or "." on a numeric column}
+    C -- Yes --> Z
+    C -- No --> D{HARDREGEX rule on column?}
+    D -- Yes --> E{Pattern matches?}
+    E -- No --> F[Invalid: submission blocked,<br/>red htInvalid + REGEX tooltip]
+    E -- Yes --> J[Valid]
+    D -- No --> G{SOFTREGEX rule on column?}
+    G -- Yes --> H{Pattern matches?}
+    H -- No --> I[Warning: yellow dc-warning-cell<br/>+ REGEX tooltip, submission allowed]
+    H -- Yes --> J[Valid]
+    G -- No --> J
+```
+
+A malformed pattern never reaches this flow: it is treated as always-valid (HARDREGEX) / never-warn (SOFTREGEX) with a `console.warn`, rather than breaking the editor.
+
+### `client/src/app/shared/dc-validator/utils/parseRegexRule.ts`
+
+Converts an authored SAS PRX pattern into a JavaScript `RegExp`:
+
+1. If the value matches `/^\/(.*)\/([a-z]*)$/s`, the delimiters are stripped and the trailing flags are passed to `new RegExp(body, flags)`. Otherwise the value is used as-is (backwards compatibility with bare patterns).
+2. Three mechanical Perl→JS translations are applied to the body:
+   - a leading `(?i)` inline modifier is removed and folded into the `i` flag;
+   - `\Q...\E` literal sequences are replaced with escaped literal text;
+   - `\A` → `^` and `\z` → `(?![\s\S])` (end-of-string anchor).
+3. Perl-only constructs that would need a capture-group-renumbering rewrite (atomic groups `(?>...)`, possessive quantifiers `a++`) are deliberately NOT translated. They throw from `new RegExp`, and every caller treats a throw as "always valid / never warn" (see below) rather than breaking the editor.
+
+### `client/src/app/shared/dc-validator/utils/isRegexRuleExempt.ts`
+
+Blank values (`undefined`, `null`, `''`) are exempt from pattern matching on any column type - use a separate NOTNULL rule if populated values must also be enforced. On numeric columns the plain SAS missing (`.`) is also exempt; special missings (`.A`-`.Z`, `._`, bare letters) are NOT exempt anywhere - being deliberately set, they are real values the pattern must match (and on a character column even `.` is real text). `isSpecialMissing` from `@sasjs/utils` is deliberately not used: its optional-dot regex would exempt any single-letter character value ("d", "z") before the regex ever ran. The check takes an `isNumeric` flag, passed by all callers (the dq validator via `dqValidate(rules, value, colType === 'numeric')`, the warning renderer via a `makeRegexWarningRenderer` argument, and `failsSoftRegex` via the column's HOT type).
+
+### HARDREGEX - blocking validation
+
+`HARDREGEX` is implemented as a cell validator in `client/src/app/shared/dc-validator/validations/dq-validation.ts`. It returns `true` (valid) for exempt values and for patterns that fail to compile (with a `console.warn`), and otherwise returns `parseRegexRule(ruleValue).test(value.toString())`. Returning `false` makes HOT mark the cell invalid, block submission, and paint it red via its standard `htInvalid` styling.
+
+### SOFTREGEX - warning renderer
+
+`client/src/app/editor/utils/regex-warning-renderer.ts` builds a display-only Handsontable renderer (registered per-column by `DcValidator.setupRules` in `client/src/app/shared/dc-validator/dc-validator.ts`). It never returns false; it only:
+
+- adds a `REGEX: <pattern>` tooltip (`td.title`) when a rule fails;
+- adds the yellow `dc-warning-cell` class when only SOFTREGEX fails.
+
+`DcValidator.failsSoftRegex(col, value)` provides the same logic outside the grid (e.g. the edit-record screen).
+
+### Precedence: HARD and SOFT on the same column
+
+Only one regex ever runs per column. If a HARDREGEX rule exists, SOFTREGEX is ignored entirely - never compiled, never evaluated - regardless of whether individual cell values pass or fail the hard rule. A value failing HARDREGEX gets the red invalid styling (blocking submission) plus a `REGEX: <pattern>` tooltip; a SOFTREGEX-only column warns in yellow without blocking. This holds in both the renderer and `failsSoftRegex`.
+
+### Other behaviour
+
+- Rows marked for delete (`_____DELETE__THIS__RECORD_____ = 'Yes'`) are not warned/validated by the renderer (except primary key columns, which still validate).
+- A malformed pattern never breaks the editor: the dq validator treats it as always-valid and the renderer disables the warning, logging to the console instead.
+- The pattern is used as authored - it is NOT auto-anchored. Authors must include `^`/`$` to match the entire cell value.
+- Column info: `client/src/app/shared/utils/col-info-html.ts` shows the applied pattern in the column-info dropdown - the HARDREGEX pattern if one exists (it is the rule actually applied when both are present), otherwise the SOFTREGEX pattern, otherwise nothing.
+
+## Testing
+
+- Unit tests: `parseRegexRule.spec.ts`, `isRegexRuleExempt.spec.ts`, `dq-validation.spec.ts`, `dc-validator.spec.ts` (under `client/src/app/shared/dc-validator/`), `client/src/app/editor/utils/regex-warning-renderer.spec.ts`, `client/src/app/shared/utils/col-info-html.spec.ts`.
+- E2E: `client/cypress/e2e/editor.cy.ts`.
+- SAS side: `sas/sasjs/services/editors/stagedata.test.3.sas`, plus seed data in `mpe_makedata.sas`: HARDREGEX "SOME_CHAR must contain 'the' or 'data'" (`/the|data/i`), SOFTREGEX "SOME_CHAR should contain the letter 't'", SOFTREGEX on PRIMARY_KEY_FIELD (`/^\d+$/` - yellow if the key contains a decimal), and HARDREGEX on SOME_SHORTNUM (`/^(?![1-5](\.\d+)?$).*/` - values 1-5 blocked; generated data starts at 6 so demos aren't blocked accidentally).

.agents/docs/releases-and-changelog.md

@@ -0,0 +1,28 @@
+# Releases and the CHANGELOG
+
+**Do not edit `CHANGELOG.md` by hand, and do not bump the version in `package.json` yourself.** Both are generated automatically by the release pipeline. Manual edits produce duplicate/colliding version sections and merge conflicts, and they are pointless because the next release overwrites them anyway.
+
+## How releases work
+
+Releases are driven by [semantic-release](https://semantic-release.gitbook.io/) from the `release` job in `.gitea/workflows/release.yaml`, which runs on every push to `main` (after the build/test jobs pass). The configuration lives in `.releaserc` at the repo root.
+
+The plugin chain (`.releaserc` `plugins`) does the following on each release:
+
+1. `@semantic-release/commit-analyzer` - inspects Conventional Commit messages since the last tag to decide the next semantic version (`fix:` -> patch, `feat:` -> minor, breaking change -> major).
+2. `@semantic-release/release-notes-generator` - builds the release notes from those commits.
+3. `@semantic-release/changelog` - **writes the new section into `CHANGELOG.md`**.
+4. `@semantic-release/npm` - updates the `version` in `package.json` (it does not publish; the package is `private`).
+5. `@semantic-release/git` - commits `CHANGELOG.md` and `package.json` back to `main` as `chore(release): <version> [skip ci]` and tags it.
+6. `@saithodev/semantic-release-gitea` - creates the Gitea release.
+
+The build assets (frontend zip, SAS 9 / Viya / SASjs Server deployment files) are attached to the release afterwards by the workflow's own `Upload assets to release` step using the Gitea API (`curl`), not by the plugin. Before creating the release the workflow first runs `semantic-release --dry-run` and aborts the job if there are no releasable changes since the last tag.
+
+Because the changelog entry and version bump are committed by the pipeline (step 5), they must **not** exist in your working tree beforehand. If they do, the release commit collides with them.
+
+## What this means for you
+
+- Never add, remove, or reorder entries in `CHANGELOG.md`.
+- Never change `version` in `package.json`.
+- Control what appears in the changelog through your **commit messages** (Conventional Commits: `fix:`, `feat:`, `feat!:`/`BREAKING CHANGE:`, plus scopes like `fix(editor): ...`). The scope and description become the changelog line.
+- If you find hand-written entries in `CHANGELOG.md` in the working tree, revert them (`git checkout CHANGELOG.md`).
+- CI does not use any local release script - the pipeline installs and runs `semantic-release` directly.

.agents/docs/replace-load-type.md

@@ -0,0 +1,97 @@
+# REPLACE Load Type — Technical Deep Dive
+
+This document describes the REPLACE load type in detail. For the overall loader architecture, the temporal model, and the other load types, see [bitemporal-dataloader.md](bitemporal-dataloader.md).
+
+## Overview
+
+REPLACE is the simplest load type and is deliberately **not** routed through `%bitemporal_dataloader`. It is implemented inline in `%mpe_targetloader` (`sas/sasjs/macros/mpe_targetloader.sas`, search for `&loadtype=REPLACE`). There is no history, no change detection, no key matching — the target table is wiped and reloaded from the staging table verbatim.
+
+## Actual load (`LOADTARGET=YES`)
+
+```sas
+%mp_lockanytable(LOCK, lib=&lib, ds=&ds, ...)
+
+data WORK.&STAGING_DS;
+  set WORK.&STAGING_DS;
+  /* only if the target contains the MPE_TABLES.VAR_PROCESSED variable: */
+  &VAR_PROCESSED = &now;
+  drop _____DELETE__THIS__RECORD_____;
+run;
+
+%if &engine_type=CAS %then %do;
+  /* prep first: cast varchar columns in a CASUSER copy of staging */
+  proc contents noprint data=&libds out=work.rpl_base_cols(keep=name type);
+  proc contents noprint data=WORK.&STAGING_DS out=work.rpl_stag_cols(keep=name type);
+  /* work.rpl_vchars = columns that are varchar in target AND in staging */
+  data casuser.&tmpds;              /* temp copy with varchars casted   */
+    length <varchar col> varchar(*); ...
+    set WORK.&STAGING_DS (rename=(<varchar col>=<tmp> ...));
+    <varchar col>=<tmp>; ... drop <tmp> ...;
+  run;
+  /* unlock + abort if any error so far - nothing destructive done yet */
+  %mp_abort(iftrue= (&syscc>0) ...)
+  /* destructive step, deliberately last before the append */
+  proc cas;
+    table.deleteRows / table={caslib="&lib",name="&ds",where="1=1"};
+  quit;
+  data &libds (append=yes) / sessref=dcsession;
+    set casuser.&tmpds;
+  run;
+  proc sql; drop table CASUSER.&tmpds; quit;
+%end;
+%else %do;
+  /* unlock + abort if any error so far - nothing destructive done yet */
+  %mp_abort(iftrue= (&syscc>0) ...)
+  proc sql;
+    delete * from &libds;
+  quit;
+  proc append base=&libds data=WORK.&STAGING_DS force nowarn; run;
+%end;
+
+%mp_lockanytable(UNLOCK, lib=&lib, ds=&ds, ...)
+```
+
+Step by step:
+
+1. **Lock** — the target is locked via `%mp_lockanytable` (control table `&dclib..MPE_LOCKANYTABLE`). This is the only concurrency guard for the whole operation.
+2. **Staging recopy** — the staging dataset is rewritten in place: the processed-timestamp column is set to the approval timestamp **only if** the target table contains the variable named by `MPE_TABLES.VAR_PROCESSED` (unlike `%bitemporal_dataloader`, there is no `PROCESSED_DTTM` fallback). The delete-flag column `_____DELETE__THIS__RECORD_____` is unconditionally dropped — per-record delete semantics do not exist in REPLACE (everything is deleted anyway), so a delete flag submitted by the user is silently discarded (a `drop` of a non-existent variable just produces a warning).
+3. **Prepare the load (CAS only)** — fixed char variables cannot be appended to CAS varchar columns, so the staging table is first copied to a CASUSER temp table with every column that is varchar in the target (and present in staging) redeclared as `varchar(*)` via generated `length` / `rename` / assignment statements. This mirrors the CAS append in `%bitemporal_dataloader`.
+4. **Pre-destructive abort check** — if `&syscc > 0` after all preparation, the target is unlocked and the macro aborts via `%mp_abort`. Nothing destructive has happened at this point, so a failed prep leaves the target intact (and without a stale lock).
+5. **Delete all rows** — every row is removed from the target while preserving structure, indexes and metadata, deliberately as the last step before the append (to minimise the time the target sits empty). On most engines this is `proc sql; delete * from &libds;` (passed through as a `DELETE` on database libraries). CAS tables do not support SQL deletes, so on the CAS engine the table is truncated instead via the `table.deleteRows` action with `where="1=1"` (same approach as `%bitemporal_closeouts`), with the libref passed as the caslib.
+6. **Append staged rows** — the entire staging table is appended. On most engines this is `proc append ... force nowarn` (`force` allows the append to proceed despite attribute mismatches, so lengths/formats may be coerced or values truncated, and columns present in only one side are handled; `nowarn` suppresses the associated warnings). On CAS the pre-cast CASUSER temp table is appended with `data &libds (append=yes) / sessref=dcsession` and then dropped.
+7. **Unlock**.
+
+## Diff screen (`LOADTARGET=NO`)
+
+When the approver reviews a REPLACE submission, no real comparison is performed:
+
+```sas
+/* is full replace so treat all staged records as new in diff screen */
+data work.outds_mod work.outds_add;
+  set work.&staging_ds;
+  output work.outds_add;   /* every staged record is "NEW" */
+run;                       /* outds_mod stays empty        */
+
+/* previous table will be considered fully deleted */
+data work.outds_del;
+  set &lib..&ds;           /* every existing record is "DELETED" */
+run;
+```
+
+The approval screen therefore always shows full-table turnover: the entire current table as deleted and the entire staging table as added, with no "modified" records and no original/current comparison.
+
+## What REPLACE does not do
+
+Because it bypasses `%bitemporal_dataloader`, none of the following apply to REPLACE:
+
+* **No row-level audit** — nothing is written to `AUDIT_LIBDS` / `MPE_AUDIT`. The record of the change is the approval package itself (staged CSV and the `TEMPDIFFS` CSV stored under `&mpelocapprovals/&LOAD_REF`).
+* **No `MPE_DATALOADS` log entry** — the load-log insert lives inside `%bitemporal_dataloader`, so REPLACE loads do not appear in load history. (Consequently the SHOW_DIFFS timestamp lookup in `postdata.sas` finds no `MPE_DATALOADS` row for a REPLACE load and falls back to the current datetime.)
+* **No PK usage** — `BUSKEY` is ignored: no uniqueness check, no dedup, no join to existing data. Staged rows are loaded exactly as submitted, duplicates included.
+* **No temporal handling** — `VAR_TXFROM`/`VAR_TXTO`/`VAR_BUSFROM`/`VAR_BUSTO` and `CLOSE_VARS` are ignored. A REPLACE table should not be treated as temporal; querying it with the usual validity filters makes no sense.
+* **No retained-key handling** — `RK_UNDERLYING` is ignored.
+* **Minimal engine-specific handling** — unlike the temporal loaders, there is no pass-through/temp-table optimisation for OLEDB, Redshift, Postgres or Snowflake. The only engine conditional is CAS, where rows are removed via the `deleteRows` action and appended via a varchar-casting CASUSER temp table and a data-step append (SQL deletes and fixed-char-to-varchar appends are not possible on CAS).
+* **Not atomic** — the delete/truncate and append are separate steps with no transaction or rollback, so a session failure between them still leaves the target empty or partially loaded (recovery is a re-approval of the same or a previous staging package). The risk is mitigated by performing all preparation first, aborting on any error before the destructive step, and executing the delete/truncate immediately before the append.
+
+## Interaction with Row Level Security
+
+REPLACE is incompatible with `EDIT`-scope RLS rules (a full-table wipe cannot honour row-level write restrictions); this is enforced at edit time in both directions — see [row-level-security.md](row-level-security.md#incompatibility-with-replace-load-type) and [issue #211](https://git.datacontroller.io/dc/dc/issues/211). `VIEW`-scope rules remain compatible.

.agents/docs/row-level-security.md

@@ -0,0 +1,225 @@
+# Row Level Security — Technical Deep Dive
+
+This document explains **how** Row Level Security (RLS) is implemented in the Data Controller backend. For the user-facing configuration guide, see [docs.datacontroller.io/row-level-security](https://docs.datacontroller.io/row-level-security/).
+
+## Overview
+
+RLS in Data Controller is implemented as **server-side WHERE clause generation**. No data leaves SAS without passing through a dynamically generated filter. The filter is built at runtime per request, based on:
+
+1. The requesting user's group memberships (SAS metadata groups + DC groups)
+2. The active rules in the `MPE_ROW_LEVEL_SECURITY` control table
+3. The access mode (VIEW / EDIT / download / upload)
+
+Because the filter is expressed as a standard SAS `WHERE` expression, it works against **any** engine — Base SAS datasets, database libraries (via implicit SQL pass-through pushdown), SPDE, CAS libnames, etc.
+
+## Request Flow
+
+```mermaid
+flowchart TD
+    A[Client request\nview / edit / download / upload] --> B{Service mode}
+    B -->|VIEW / EDIT / DLOAD| C["%mpe_filtermaster(mode, libds)"]
+    B -->|ULOAD stagedata.sas| C
+    C --> D["%mpe_getgroups()\nmetadata groups + MPE_GROUPS"]
+    D --> E{User in &mpeadmins?}
+    E -->|Yes| F[No RLS filter\n1=1]
+    E -->|No| G[Lookup active rules in\nMPE_ROW_LEVEL_SECURITY\nfor libref.table + user's groups]
+    G --> H{Rules found?}
+    H -->|No| F
+    H -->|Yes| I["%mp_filtergenerate()\nper group, OR'd together"]
+    I --> J[WHERE clause written\nto temp fileref]
+    F --> J
+    J --> K{Read or Write?}
+    K -->|Read\nviewdata / getdata / getrawdata| L["where %inc filtref;;\nrows filtered server-side"]
+    K -->|Write\nstagedata| M[Inverse filter\nwhere not( filtref )]
+    M --> N{badrecords > 0?}
+    N -->|Yes| O[Abort submission\nSecurity Problem]
+    N -->|No| P[Staging proceeds\nto approval workflow]
+```
+
+## Key Components
+
+| Component | Location | Role |
+|---|---|---|
+| `MPE_ROW_LEVEL_SECURITY` | `&mpelib` (DC control library) | The rule table (scope, group, libref, table, logic, subgroup, variable, operator, raw value, active flag) |
+| `%mpe_filtermaster()` | `sas/sasjs/macros/mpe_filtermaster.sas` | Master macro that assembles the full WHERE clause for a request |
+| `%mpe_getgroups()` | `sas/sasjs/macros/mpe_getgroups.sas` | Resolves group membership (metadata groups via `%dc_getusergroups` + `MPE_GROUPS` DC-internal groups) |
+| `%mp_filtergenerate()` | SASjs core | Converts a query table (logic/subgroup/variable/operator/value rows) into WHERE clause text |
+| `%mp_filtercheck()` | SASjs core | Validates rule syntax at *edit time* (defence against SAS code injection) |
+| `mpe_row_level_security_postedit.sas` | `sas/sasjs/services/hooks/` | Post-edit hook that runs `%mp_filtercheck` whenever the RLS table itself is edited |
+
+## The Modes
+
+`%mpe_filtermaster` accepts a `mode` parameter, and every service that surfaces data calls it with the appropriate mode:
+
+| Mode | Caller | Purpose |
+|---|---|---|
+| `VIEW` | `services/public/viewdata.sas`, `getchangeinfo.sas` | Read-only table viewer |
+| `EDIT` | `services/editors/getdata.sas` | The EDIT grid (adds "current records only" validity filtering) |
+| `DLOAD` | `services/public/getrawdata.sas` | Raw file downloads (RLS scope treated as `VIEW`) |
+| `ULOAD` | `services/editors/stagedata.sas` | **Upload validation** (RLS scope treated as `EDIT`) |
+
+Scope mapping: `DLOAD` requests match rules with `RLS_SCOPE in ('VIEW','ALL')`; `ULOAD` requests match rules with `RLS_SCOPE in ('EDIT','ALL')`.
+
+## Execution Flow of `%mpe_filtermaster`
+
+The macro writes the final WHERE expression to a temporary **fileref** (`outref`), line by line. (A fileref is used because a generated filter may exceed the 64k macro variable limit — and note that `%include` of a fileref is not allowed directly in a `proc sql` where clause, hence callers typically use it in a DATA step or data step view.)
+
+### 1. User-supplied filter (FILTER_RK)
+
+If the request includes a stored filter (`filter_rk > 0`), its clauses are read from `MPE_FILTERANYTABLE` / `MPE_FILTERSOURCE` and generated first via `%mp_filtergenerate`. RLS clauses are then **AND-ed on top** — a user filter can only ever narrow results, never widen them beyond RLS.
+
+### 2. Validity-date filtering (EDIT / DLOAD only)
+
+`MPE_TABLES` may define `VAR_TXFROM` / `VAR_TXTO` (SCD2-style validity variables) for the target table. Unless the user explicitly filtered on those variables, the macro appends:
+
+```
+("<current datetime>"dt < VAR_TXTO)
+```
+
+so that only current records are surfaced in the EDIT grid and downloads.
+
+### 3. Group resolution and admin bypass
+
+```sas
+%mpe_getgroups(user=%mf_getuser(), outds=work.groups)
+```
+
+Groups come from two sources, concatenated:
+
+* SAS metadata groups (Viya / EBI / Base-specific logic in `%dc_getusergroups`)
+* The `MPE_GROUPS` DC table (group assignments managed inside Data Controller)
+
+If the user is a member of the `&mpeadmins` group, **RLS is skipped entirely** — admins always see all rows.
+
+### 4. Rule extraction
+
+Non-admin users trigger a lookup of active, current rules:
+
+```sas
+create table work.&rlsds as
+  select rls_group, rls_group_logic, rls_subgroup_logic, rls_subgroup_id,
+         rls_variable_nm, rls_operator_nm, rls_raw_value
+  from &mpelib..mpe_row_level_security
+  where &dc_dttmtfmt. lt tx_to          /* only current (non-deleted) rules */
+    and rls_scope in ("&scopeval",'ALL')
+    and upcase(rls_group) in (select upcase(groupname) from work.groups)
+    and rls_libref = "<libref>" and rls_table = "<dsname>"
+    and rls_active = 1
+  order by rls_group, rls_subgroup_id;
+```
+
+### 5. Clause assembly
+
+If rules exist, they are appended to the fileref as `AND ( ... )`. Each **group** the user belongs to contributes one sub-filter, and the group-level sub-filters are joined with `OR`:
+
+```
+AND ( <group 1 filter> OR <group 2 filter> ... )
+```
+
+Each group's filter is produced by `%mp_filtergenerate`, which honours:
+
+* `RLS_GROUP_LOGIC` — how subgroups (identified by `RLS_SUBGROUP_ID`) are joined
+* `RLS_SUBGROUP_LOGIC` — how individual clauses within a subgroup are joined (AND/OR)
+
+So membership in multiple groups is **permissive** (OR): the user sees the union of rows permitted by each of their groups.
+
+### 6. Empty-filter fallback
+
+If nothing was written to the fileref (no stored filter, no validity vars, no matching RLS rules), the macro writes a literal `1=1` so the fileref can always be consumed as a valid WHERE expression. Absence of rules therefore means **no restriction** — RLS is opt-in per table/group.
+
+## How Callers Apply the Filter
+
+### Read path (viewdata.sas)
+
+```sas
+%mpe_filtermaster(VIEW, &libds, dclib=&mpelib, filter_rk=&filter_rk,
+  outref=filtref, outds=work.query)
+
+data work.viewdata;
+  set &libds;
+  where %inc filtref;;
+  if _n_ > &DC_MAXOBS_WEBVIEW then stop;
+run;
+```
+
+The fileref is `%include`d directly inside the `where` statement — the filter never passes through client-visible state, so it cannot be tampered with. For database libraries the WHERE expression is pushed down to the database by the SAS engine.
+
+### Write path (stagedata.sas) — inverse filter
+
+Uploads cannot be filtered; instead the filter is **inverted** and any submitted row matching the inverse is rejected:
+
+```sas
+%mpe_filtermaster(ULOAD, &libds, dclib=&mpelib, outref=filtref, ...)
+
+/* prepare inverse query */
+data _null_;
+  infile filtref end=eof;
+  file &tempref;
+  if _n_=1 then put 'where not(';
+  input;  put _infile_;
+  if eof then put ')';
+run;
+
+data work.badrecords;
+  set work.jsdata;      /* rows submitted by the user */
+  %inc &tempref/source2;;
+run;
+
+%mp_abort(iftrue=(%mf_nobs(work.badrecords)>0)
+  ,msg=%str(Security Problem - N unauthorised records submitted))
+```
+
+If even one submitted row falls outside the user's permitted row set, the entire staging request is aborted before any approval/apply step.
+
+## Incompatibility with REPLACE Load Type
+
+RLS with `EDIT` scope is **incompatible** with tables configured with `LOAD_TYPE=REPLACE` in `MPE_TABLES`. A REPLACE load wipes and reloads the entire target table, so row-level filtering of submitted records cannot be enforced meaningfully (the rows a user is *not* allowed to see would also be deleted). Backend validations therefore abort in both directions (see [issue #211](https://git.datacontroller.io/dc/dc/issues/211)):
+
+1. **`mpe_row_level_security_postedit.sas`** — aborts when activating a rule with `RLS_SCOPE in ('EDIT','ALL')` against a table whose current `MPE_TABLES` record has `LOADTYPE='REPLACE'`.
+2. **`mpe_tables_postedit.sas`** — aborts when setting `LOADTYPE='REPLACE'` on a table that already has active, current `RLS_SCOPE in ('EDIT','ALL')` rules in `MPE_ROW_LEVEL_SECURITY`.
+
+`VIEW`-scope rules remain compatible with REPLACE loads, since they only affect read paths.
+
+## Edit-Time Validation (Injection Defence)
+
+Because `RLS_RAW_VALUE` is free text that ends up inside a generated WHERE clause, it is a potential SAS code-injection vector. Mitigations:
+
+1. **`mpe_row_level_security_postedit.sas`** — a post-edit hook on the `MPE_ROW_LEVEL_SECURITY` table itself. Every newly staged rule (with `rls_active=1`) is grouped by target `libref.table` and run through `%mp_filtercheck(targetds=..., abort=YES)`, which compiles/tests each clause against the real target table and rejects the whole submission on invalid syntax (see [mp_filtercheck](https://core.sasjs.io/mp__filtercheck_8sas.html)).
+2. **Format rules** enforced by validation: character values must be single quoted, `IN`/`NOT IN` values must be bracketed, `BETWEEN` must contain `AND`.
+
+Additionally, editing `MPE_ROW_LEVEL_SECURITY` is itself a Data Controller table edit, so it goes through the normal approval workflow, audit trail (`MPE_AUDIT`), and can be column-restricted via [Column Level Security](https://docs.datacontroller.io/column-level-security/).
+
+## Worked Example
+
+Given these active rules (all for `MYLIB.MYDS`, `RLS_ACTIVE=1`):
+
+| SCOPE | GROUP | GROUP_LOGIC | SUBGRP_LOGIC | SUBGRP_ID | VAR | OP | VALUE |
+|---|---|---|---|---|---|---|---|
+| ALL | Group 1 | AND | AND | 1 | VAR_2 | IN | ('this','or') |
+| ALL | Group 1 | AND | AND | 1 | VAR_3 | < | 42 |
+| ALL | Group 2 | AND | AND | 1 | VAR_4 | CONTAINS | 'xyz' |
+
+A non-admin user in **both** groups, opening the VIEW page, gets a fileref containing:
+
+```
+AND ( (VAR_2 IN ('this','or') AND VAR_3 < 42) OR (VAR_4 CONTAINS 'xyz') )
+```
+
+resulting in:
+
+```sas
+data work.viewdata;
+  set mylib.myds;
+  where (VAR_2 IN ('this','or') AND VAR_3 < 42) OR (VAR_4 CONTAINS 'xyz');
+run;
+```
+
+The same user submitting an EDIT upload has the inverse applied to their staged rows; any row not matching the expression above aborts the submission.
+
+## Summary of Security Properties
+
+* **Enforced server-side** in every read service (VIEW/EDIT/DLOAD) and every write service (ULOAD via inverse filter).
+* **Admin bypass** is explicit (`&mpeadmins` group membership check).
+* **Multi-group semantics are OR** (union of permitted rows); rules within a group/subgroup are AND/OR per configuration.
+* **Fail-open by design**: if no rules match a table, it is unrestricted — RLS must be opted into per table.
+* **Injection-resistant**: values are validated with `%mp_filtercheck` at the time rules are edited, not at query time.

.agents/docs/testing.md

@@ -0,0 +1,21 @@
+# Testing
+
+Backend (SAS) tests are run with the sasjs CLI from the `sas/` directory.
+
+## Commands
+
+- Full deploy + test cycle: `npm run 4gl` (compiles, deploys to the 4gl target, runs makedata) then `sasjs test -t 4gl`.
+- Run tests only (no rebuild/redeploy): `sasjs test -t 4gl`.
+- Run a subset of tests: `sasjs test -t 4gl SOMESTRING` — the positional argument filters to matching tests (e.g. `sasjs test -t 4gl stagedata.test.3`).
+
+## Results
+
+- Test results: `sas/sasjsresults/testResults.json` / `.csv` / `.xml`
+- Individual test logs: `sas/sasjsresults/logs/<testsuite>.log` (e.g. `services_editors_stagedata.test.3.log`)
+- Coverage: `sas/sasjsresults/coverage.lcov`
+
+## Notes
+
+- Test source files live in `sas/sasjs/**`; `sas/sasjsbuild/` is generated build output — do not hand-edit it.
+- `sasjs test` executes tests against the deployed app, so run `npm run 4gl` first after changing any service/hook/test code.
+- Assertions are made with `%mp_assert()`; results are written to `work.test_results`.

.agents/skills/dc-sas/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: dc-sas
+description: >
+  Use this skill alongside the sasjs/skills collection (sas, sasjs-core, sasjs-cli) when working on
+  Data Controller SAS code. Covers the repo-specific SAS knowledge that is NOT in those skills —
+  DC test-state conventions (MPE control tables, dctest, %let syscc) and the chunked-deploy
+  strategy for the huge generated build script (sasjsbuild/viya.sas). For general SAS language,
+  @sasjs/core macro, and @sasjs/cli guidance, rely on the sas, sasjs-core and sasjs-cli skills.
+---
+
+# SAS Development in Data Controller
+
+The sas, sasjs-core and sasjs-cli skills cover general SAS language and SASjs conventions (macro
+quoting, `%mp_assert*` testing style, `sasjs lint`, `sasjs run`, `sasjsbuild/` being generated
+output). These notes only cover the parts specific to Data Controller.
+
+
+## Tests must be idempotent
+
+A test file must pass when run repeatedly (including after a run that failed partway).
+
+- Clean up **all** persistent DC state, not just the obvious one: `MPE_TABLES` registrations,
+  `MPE_LOCKANYTABLE` lock records (a run dying between LOCK and UNLOCK leaves a stale `LOCKED`
+  row), physical tables in `dctest` (`proc datasets ... delete`), and global macro variables
+  created via `select ... into:` (`%symdel`).
+
+## Chunked deploy to Viya
+
+The full DC build script (`sasjsbuild/viya.sas`) is very large (11+ MB / 300k+ lines). The Viya
+compute API can hang or fail when submitting a file this size in a single request.
+
+**Chunked deploy.** Split the build script at `%let path=<folder>` boundaries — these are clean
+section breaks between service/test folders (always preceded by blank lines, never inside a data
+step). Each sub-chunk must be prepended with the shared header (the first ~3827 lines containing
+macro definitions, `appLoc` setup, and logging options:
+
+`options ps=max nonotes nosgen nomprint nomlogic nosource2 nosource noquotelenmax;`
+
+Logging is already suppressed in the header — no extra action needed. Keep each chunk under ~1.5
+MB. The `tests/macros`, `tests/services`, and streaming-app tail sections are the largest and may
+need further sub-splitting at `%let service=` boundaries.
+
+When splitting mid-folder (between services in the same folder), the sub-chunk that starts
+mid-folder must re-assert `%let path=<folder>;` before its first `%let service=` line — otherwise
+`&path` is unresolved and the `%mv_createwebservice(path=&appLoc/&path, ...)` call will abort with
+a recursive reference error.
+
+Deploy each chunk in order with `sasjs run <chunk>.sas -t <target>`. After all chunks are
+deployed, run `sasjs request services/admin/makedata -d deploy/makeDataViya.json -t <target>` to
+create the database.
+
+**Non-fatal errors.** `ERROR: Unauthorized` on `/dataSources/providers/Compute/` lines in the
+log are expected for non-admin Viya users — they come from the Data Sources API during
+lineage/catalog refresh and do not affect the deploy.
+
+## Repo conventions for .sas files
+
+- Test files are named `<thing>.test.sas` (or `<thing>.test.N.sas`) and run via
+  `npm run 4gl && sasjs test -t 4gl` from `sas/` — see `.agents/docs/testing.md`.
+- `sas/sasjsbuild/` is generated build output — never hand-edit it; edit sources under
+  `sas/sasjs/` only.
+
+## Temp and scratch files stay out of the repo
+
+Transient artifacts from manual test runs against sasjs-server — captured `_webout` JSON
+responses (e.g. `*_out.json`), request/response logs (e.g. `*.log`), and iteration snapshots
+(`vd_out2.json`, `stage_check2.json`, etc.) — must not be left in the working tree. They
+clutter `git status`, are never referenced by source or tests, and easily leak local
+filesystem paths (the sasjs-server session dir, `/home/.../sasjs_root/sessions/.../`) into
+committed history.
+
+Write them to a gitignored tmp location instead. The repo already provides two:
+
+- `tmp/` (gitignored at repo root) — general scratch space.
+- `sas/tmp/` (gitignored via the root `tmp/` rule) — for SAS-side artifacts.
+
+If a helper script dumps captured output for comparison during a debug session, point it at
+`tmp/` (or `sas/tmp/` for SAS-local paths) rather than alongside the tracked mocks in
+`sas/mocks/`. The tracked mock fixtures live under `sas/mocks/sas9/` and
+`sas/mocks/sasjs/services/`; loose `*_out.json` / `*.log` files at the `sas/mocks/` root are
+not mocks, they are leftover captures — remove them with `git clean -fd sas/mocks/` or
+write to `tmp/` in the first place.

.agents/skills/handsontable/SKILL.md

@@ -0,0 +1,606 @@
+---
+name: handsontable
+description: >
+  Use this skill whenever the user asks about Handsontable — a JavaScript data grid component with
+  spreadsheet-like UX. Triggers include: mentions of "handsontable", "HotTable", "data grid",
+  "@handsontable/react-wrapper", spreadsheet component in React/Angular/Vue, HyperFormula formulas
+  inside a grid, cell types (dropdown, checkbox, date, numeric) in a grid context, or questions
+  about Handsontable theming, plugins, hooks, configuration options, or column/row features. Also
+  trigger when the user wants to add an editable spreadsheet-like table to a web app, or asks about
+  copy/paste, sorting, filtering, frozen rows/columns, merged cells, or context menus in a grid.
+  This skill covers Handsontable used with any framework (React, Angular, Vue 3, vanilla JS) and
+  HyperFormula as the Formulas plugin engine inside Handsontable. Do NOT use this skill for
+  headless/standalone HyperFormula usage without Handsontable — that is covered by the separate
+  "hyperformula" skill.
+---
+
+# Handsontable
+
+Handsontable is a JavaScript **data grid component** (not a full spreadsheet application) that
+brings spreadsheet-like UX to web apps: cell editing, copy/paste, sorting, filtering, formulas,
+keyboard navigation, context menus, merged cells, frozen rows/columns, conditional formatting, data
+validation, pagination, and 400+ built-in formulas via HyperFormula.
+
+- **Latest version:** 17.1.0 (May 2026)
+- **Frameworks:** Vanilla JS/TS, React (`@handsontable/react-wrapper`), Angular (`@handsontable/angular-wrapper`), Vue 3 (`@handsontable/vue3`)
+- **React wrapper requires:** React 18+
+- **License:** Dual — free for non-commercial use (`licenseKey: 'non-commercial-and-evaluation'`), paid for commercial. Per-developer annual license, offline validation (no server connection). Tiers: Hobby (free, non-commercial), Trial (free 45 days), Standard (from $999/yr), Priority (from $1,299/yr), Enterprise (custom). See [Pricing](https://handsontable.com/pricing).
+
+Always check `references/docs-map.md` (in this skill folder) for the full organized link directory
+when you need to point the user to specific documentation or need to look up more info.
+
+### What this skill does NOT cover
+
+- **Standalone HyperFormula** (headless formula engine without a grid UI) — use the "hyperformula" skill instead.
+- **Other data grid libraries** (AG Grid, TanStack Table, etc.).
+- **Full spreadsheet applications** — Handsontable is a component you embed, not a standalone app like Google Sheets.
+
+---
+
+## React Quick Start (Recommended)
+
+### Install
+
+```bash
+npm install handsontable @handsontable/react-wrapper
+```
+
+### Minimal working example
+
+```jsx
+import { HotTable } from '@handsontable/react-wrapper';
+import { registerAllModules } from 'handsontable/registry';
+import 'handsontable/styles/handsontable.min.css';
+import 'handsontable/styles/ht-theme-main.min.css';
+
+registerAllModules();
+
+const MyGrid = () => (
+  <HotTable
+    themeName="ht-theme-main"
+    data={[
+      ['', 'Tesla', 'Volvo', 'Toyota', 'Ford'],
+      ['2019', 10, 11, 12, 13],
+      ['2020', 20, 11, 14, 13],
+      ['2021', 30, 15, 12, 13],
+    ]}
+    colHeaders={true}
+    rowHeaders={true}
+    height="auto"
+    autoWrapRow={true}
+    autoWrapCol={true}
+    licenseKey="non-commercial-and-evaluation"
+  />
+);
+
+export default MyGrid;
+```
+
+Key points:
+- `registerAllModules()` registers every built-in plugin. To reduce bundle size, import only what
+  you need — see [Modules guide](https://handsontable.com/docs/react-data-grid/modules/).
+- `height` is required (or the grid won't render). Use `"auto"`, a pixel number, or a CSS string.
+- All Handsontable configuration options are passed as props on `<HotTable>`.
+- Full installation guide: https://handsontable.com/docs/react-data-grid/installation/
+
+---
+
+## Vanilla JS Quick Start
+
+### Install
+
+```bash
+npm install handsontable
+```
+
+### CDN (jsDelivr)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/handsontable/dist/handsontable.full.min.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable/styles/handsontable.min.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable/styles/ht-theme-main.min.css" />
+```
+
+To pin a specific version, add `@17.1` after `handsontable` in the URL (e.g.,
+`handsontable@17.1/dist/handsontable.full.min.js`).
+
+### Minimal working example
+
+```js
+import Handsontable from 'handsontable';
+import 'handsontable/styles/handsontable.min.css';
+import 'handsontable/styles/ht-theme-main.min.css';
+
+const container = document.getElementById('grid');
+
+new Handsontable(container, {
+  data: [
+    ['', 'Tesla', 'Volvo', 'Toyota', 'Ford'],
+    ['2019', 10, 11, 12, 13],
+    ['2020', 20, 11, 14, 13],
+    ['2021', 30, 15, 12, 13],
+  ],
+  colHeaders: true,
+  rowHeaders: true,
+  height: 'auto',
+  themeName: 'ht-theme-main',
+  autoWrapRow: true,
+  autoWrapCol: true,
+  licenseKey: 'non-commercial-and-evaluation',
+});
+```
+
+Full JS docs: https://handsontable.com/docs/javascript-data-grid/installation/
+
+---
+
+## Other Frameworks
+
+### Angular (v17–19)
+
+```bash
+npm install handsontable @handsontable/angular-wrapper
+```
+
+The Angular wrapper was modernized in Handsontable v17.1 to align with Angular 17–19, simplifying setup and reducing dependencies. Earlier Angular versions are no longer the target — upgrade Angular first if you're below v17.
+
+Docs: https://handsontable.com/docs/angular-data-grid/installation/
+
+### Vue 3
+
+```bash
+npm install handsontable @handsontable/vue3
+```
+
+Docs: https://handsontable.com/docs/react-data-grid/vue3-installation/
+
+All framework wrappers share the same version number as the core library and expose the same
+configuration options. The React examples in this skill translate directly — just use the
+framework's component syntax. Note: Vue 2 (`@handsontable/vue`) is deprecated — use Vue 3.
+
+---
+
+## Theming: Light / Dark / Auto
+
+Handsontable v15+ includes a built-in theme system. Three themes ship out of the box: **main**
+(default, spreadsheet-like), **horizon** (clean, analytics-focused), **classic** (legacy
+replacement).
+
+### CSS file approach (simplest)
+
+Import the base stylesheet plus a theme:
+
+```js
+import 'handsontable/styles/handsontable.min.css';
+import 'handsontable/styles/ht-theme-main.min.css';
+```
+
+Then set the theme on the grid:
+
+```jsx
+<HotTable themeName="ht-theme-main" /* ... */ />
+```
+
+**Dark mode:**
+- System preference (auto): `themeName="ht-theme-main-dark-auto"`
+- Forced dark: `themeName="ht-theme-main-dark"`
+
+Replace `main` with `horizon` or `classic` for other themes.
+
+### Theme API approach (runtime switching)
+
+```js
+import { mainTheme, registerTheme } from 'handsontable/themes';
+
+const theme = registerTheme(mainTheme)
+  .setColorScheme('auto')       // 'light' | 'dark' | 'auto'
+  .setDensityType('comfortable'); // 'compact' | 'default' | 'comfortable'
+```
+
+Then pass it as a prop:
+
+```jsx
+<HotTable theme={theme} /* ... */ />
+```
+
+### CDN theme files
+
+```html
+<!-- Theme CSS (includes light and dark mode support) -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable/styles/ht-theme-main.min.css" />
+```
+
+In v17, dark mode is controlled via `themeName` or the Theme API — there are no separate `-dark` or
+`-dark-auto` CSS files. Load the base theme CSS above and set the mode at runtime.
+
+For CSS variable customization, the Theme Builder, Figma design system, and 200+ design tokens, see:
+- [Themes guide](https://handsontable.com/docs/react-data-grid/themes/)
+- [Theme customization](https://handsontable.com/docs/react-data-grid/theme-customization/)
+- [Theme Builder tool](https://handsontable.com/theme-builder)
+
+---
+
+## Common Configuration Patterns
+
+All options below are passed as props on `<HotTable>` (React) or in the config object (vanilla JS).
+For the full options reference: https://handsontable.com/docs/react-data-grid/api/options/
+
+### Data binding
+
+```jsx
+// Array of arrays
+data={[['A1', 'B1'], ['A2', 'B2']]}
+
+// Array of objects
+data={[{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]}
+columns={[{ data: 'id' }, { data: 'name' }]}
+```
+
+Docs: https://handsontable.com/docs/react-data-grid/binding-to-data/
+
+### Column & row headers
+
+```jsx
+colHeaders={['ID', 'Name', 'Price']}  // custom labels, or {true} for A, B, C...
+rowHeaders={true}                      // 1, 2, 3... or pass an array
+```
+
+### Column types (cell types)
+
+Set via the `columns` array or `cells` function. Built-in types:
+
+- `text` (default), `numeric`, `date`, `time`, `checkbox`, `select`, `dropdown`,
+  `autocomplete`, `password`, `handsontable` (nested grid), `multiselect` (v17+)
+
+```jsx
+columns={[
+  { data: 'name', type: 'text' },
+  { data: 'price', type: 'numeric', numericFormat: { pattern: '$0,0.00' } },
+  { data: 'active', type: 'checkbox' },
+  { data: 'category', type: 'dropdown', source: ['A', 'B', 'C'] },
+]}
+```
+
+Full cell types reference: https://handsontable.com/docs/react-data-grid/cell-type/
+
+### Sorting & filtering
+
+```jsx
+columnSorting={true}        // single-column sort
+// or
+multiColumnSorting={true}   // multi-column sort
+
+filters={true}              // enable column filters
+dropdownMenu={true}         // column header menu with filter UI
+```
+
+### Frozen rows/columns
+
+```jsx
+fixedRowsTop={1}
+fixedRowsBottom={1}
+fixedColumnsStart={2}
+```
+
+### Other common options
+
+```jsx
+readOnly={true}                 // entire grid read-only (or per-cell/column)
+contextMenu={true}              // right-click menu
+mergeCells={[{ row: 0, col: 0, rowspan: 2, colspan: 2 }]}
+manualColumnResize={true}
+manualRowResize={true}
+stretchH="all"                  // stretch columns to fill width: 'none' | 'last' | 'all'
+```
+
+### Per-column config with HotColumn (React)
+
+```jsx
+import { HotTable, HotColumn } from '@handsontable/react-wrapper';
+
+<HotTable data={data} licenseKey="non-commercial-and-evaluation">
+  <HotColumn title="Name" data="name" />
+  <HotColumn title="Active" data="active" type="checkbox" />
+</HotTable>
+```
+
+Docs: https://handsontable.com/docs/react-data-grid/hot-column/
+
+---
+
+## HyperFormula Integration (Formulas Plugin)
+
+HyperFormula powers Handsontable's Formulas plugin, providing 400+ spreadsheet functions (SUM,
+AVERAGE, IF, VLOOKUP, etc.). This section covers using HyperFormula **inside** Handsontable only.
+
+### Install
+
+```bash
+npm install hyperformula
+```
+
+> **Note:** Starting in Handsontable v18, HyperFormula will no longer be bundled. Install it
+> separately and pass it to the Formulas plugin.
+
+### CDN
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/hyperformula/dist/hyperformula.full.min.js"></script>
+```
+
+### Simple setup (auto-created instance)
+
+Pass the `HyperFormula` class directly — Handsontable creates an instance automatically:
+
+```jsx
+import { HyperFormula } from 'hyperformula';
+
+<HotTable
+  data={[
+    ['10', '20', '=SUM(A1:B1)'],
+    ['30', '40', '=SUM(A2:B2)'],
+  ]}
+  formulas={{ engine: HyperFormula }}
+  colHeaders={true}
+  licenseKey="non-commercial-and-evaluation"
+/>
+```
+
+### External instance (for multi-sheet or shared engine)
+
+Create a HyperFormula instance with the `'internal-use-in-handsontable'` license key:
+
+```jsx
+import { HyperFormula } from 'hyperformula';
+
+const hfInstance = HyperFormula.buildEmpty({
+  licenseKey: 'internal-use-in-handsontable',
+});
+
+// Sheet 1
+<HotTable
+  data={data1}
+  formulas={{ engine: hfInstance, sheetName: 'Sheet1' }}
+  licenseKey="non-commercial-and-evaluation"
+/>
+
+// Sheet 2 — shares the same engine, enabling cross-sheet references
+<HotTable
+  data={data2}
+  formulas={{ engine: hfInstance, sheetName: 'Sheet2' }}
+  licenseKey="non-commercial-and-evaluation"
+/>
+```
+
+Cross-sheet formula example: `=SUM(Sheet1!A:A)`
+
+### Named expressions
+
+```jsx
+formulas={{
+  engine: HyperFormula,
+  namedExpressions: [
+    { name: 'TAX_RATE', expression: 0.21 },
+  ],
+}}
+```
+
+Use in cells: `=A1 * TAX_RATE`
+
+### Listening for formula changes
+
+```jsx
+<HotTable
+  formulas={{ engine: HyperFormula }}
+  afterFormulasValuesUpdate={(changes) => {
+    changes.forEach((c) => console.log(c.address, c.newValue));
+  }}
+/>
+```
+
+### Known limitations
+
+- Formulas don't work with nested object data.
+- Moving rows/columns with formulas requires the ManualRowMove / ManualColumnMove plugins (not IndexMapper).
+- `getSourceData()` operates on physical indexes; formulas use visual indexes.
+
+Full guide: https://handsontable.com/docs/react-data-grid/formula-calculation/
+HyperFormula functions list: https://hyperformula.handsontable.com/docs/guide/built-in-functions.html
+HyperFormula version compatibility table: https://handsontable.com/docs/react-data-grid/formula-calculation/#hyperformula-version-support
+
+---
+
+## Server-side data with DataProvider (v17.1+)
+
+The **DataProvider plugin** (new in v17.1) wires the grid up to a remote data source so rows are fetched, sorted, and mutated server-side instead of held in memory. Use it for datasets too large to load up front, or when the source of truth lives in a backend.
+
+The `dataProvider` option is an object with five required keys: a row-id resolver, a paginated `fetchRows` callback, and three mutation callbacks. For a read-only grid, stub the mutation callbacks with `async () => {}` — they must still be present.
+
+```jsx
+<HotTable
+  colHeaders={['ID', 'Name', 'Email']}
+  pagination={{ pageSize: 25 }}
+  columnSorting={true}
+  emptyDataState={true}
+  height={360}
+  licenseKey="non-commercial-and-evaluation"
+  dataProvider={{
+    // Required: how to extract a stable id from each row
+    rowId: 'id',
+
+    // Required: paginated fetch. `sort` is null when no column is sorted.
+    // Second arg carries an AbortSignal — pass it to fetch() so the plugin
+    // can cancel superseded requests when the user pages/sorts quickly.
+    async fetchRows({ page, pageSize, sort }, { signal }) {
+      const params = new URLSearchParams({ page, pageSize });
+      if (sort) {
+        // sort = { prop: string, order: 'asc' | 'desc' }
+        params.set('sortBy', sort.prop);
+        params.set('order', sort.order);
+      }
+      const res = await fetch(`/api/users?${params}`, { signal });
+      const { rows, totalRows } = await res.json();
+      return { rows, totalRows };
+    },
+
+    // Required. Stub with async () => {} if your grid is read-only.
+    // The plugin auto-refetches the current page after each callback resolves.
+    // See the plugin API ref for the exact payload shapes.
+    onRowsCreate: async () => {},
+    onRowsUpdate: async () => {},
+    onRowsRemove: async () => {},
+  }}
+/>
+```
+
+### Loading and error UI
+
+The plugin fires three hooks you can wire up as `<HotTable>` props for loading indicators and error surfaces:
+
+- `beforeDataProviderFetch(params)` — fires before each fetch. `params.skipLoading` is set when the plugin wants to suppress your loading indicator (e.g., during a quick refetch).
+- `afterDataProviderFetch(result)` — fires after a successful fetch.
+- `afterDataProviderFetchError(error)` — fires when `fetchRows` throws or returns a rejected promise.
+
+### Companion options
+
+The plugin is built to pair with `pagination` (paginates server-side), `columnSorting` (single-column server-side sort), and `emptyDataState` (loading + empty state UI). Enable all three when you use DataProvider.
+
+### Authoritative references
+
+- Guide: https://handsontable.com/docs/react-data-grid/server-side-data-fetching/
+- Recipe (REST API): https://handsontable.com/docs/react-data-grid/recipes/data-management/load-data-rest-api/
+- Plugin API: https://handsontable.com/docs/react-data-grid/api/data-provider/
+
+## Notifications (v17.1+)
+
+The **Notification plugin** (new in v17.1) shows non-blocking toast notifications anchored to the grid — useful for confirming saves, surfacing validation errors, or signaling background sync state. Enable with `notifications: true` and trigger via `hot.getPlugin('notifications').showMessage(...)`. See the plugin guide for placement, severity levels, and auto-dismiss timing: https://handsontable.com/docs/react-data-grid/notification/
+
+---
+
+## Events & Hooks
+
+Handsontable hooks are passed as props on `<HotTable>`:
+
+```jsx
+<HotTable
+  afterChange={(changes, source) => {
+    if (source !== 'loadData') {
+      console.log('Cell changed:', changes);
+    }
+  }}
+  beforeChange={(changes, source) => {
+    // Return false to cancel the edit
+  }}
+  afterSelection={(row, col, row2, col2) => {
+    console.log('Selected:', row, col, 'to', row2, col2);
+  }}
+/>
+```
+
+There are 100+ hooks available. Full reference: https://handsontable.com/docs/react-data-grid/api/hooks/
+
+Guide: https://handsontable.com/docs/react-data-grid/events-and-hooks/
+
+---
+
+## Accessing the Instance (Ref)
+
+Use a ref to call Handsontable's core methods:
+
+```jsx
+import { useRef } from 'react';
+
+const MyGrid = () => {
+  const hotRef = useRef(null);
+
+  const handleClick = () => {
+    const hot = hotRef.current?.hotInstance;
+    if (hot) {
+      console.log(hot.getData());       // get all data
+      hot.selectCell(0, 0);             // select a cell
+    }
+  };
+
+  return (
+    <>
+      <HotTable ref={hotRef} /* ...options */ />
+      <button onClick={handleClick}>Get Data</button>
+    </>
+  );
+};
+```
+
+Core API reference: https://handsontable.com/docs/react-data-grid/api/core/
+
+---
+
+## Performance & Large Datasets
+
+Handsontable virtualizes rendering automatically — only visible rows and columns are in the DOM, so
+grids with 10k–100k+ rows perform well out of the box. For bulk programmatic updates, wrap mutations
+in `batch()` to defer re-rendering until all changes are applied:
+
+```jsx
+hotRef.current.hotInstance.batch(() => {
+  // set many cells, add rows, etc.
+});
+```
+
+For further tuning (disabling auto-size, reducing plugin overhead), see:
+- [Performance guide](https://handsontable.com/docs/react-data-grid/performance/)
+- [Batch operations](https://handsontable.com/docs/react-data-grid/batch-operations/)
+- [Bundle size optimization](https://handsontable.com/docs/react-data-grid/bundle-size/)
+
+---
+
+## Recipes (v17+)
+
+Handsontable v17 introduced a Recipes section in the docs — ready-made patterns for common use cases
+(data validation workflows, dynamic column generation, etc.). Check the recipes index before building
+something from scratch: https://handsontable.com/docs/react-data-grid/recipes/
+
+---
+
+## Common Pitfalls
+
+- **Forgetting `height`**: The grid won't render without a `height` prop. Use `"auto"`, a pixel value, or a CSS string.
+- **Not filtering `loadData` in `afterChange`**: The `afterChange` hook fires on initial data load with `source === 'loadData'`. Always check the source to avoid infinite loops when syncing changes back to state.
+- **Using the old wrapper packages**: v17 removed `@handsontable/react` and `@handsontable/angular`. Use `@handsontable/react-wrapper` and `@handsontable/angular-wrapper`.
+- **Using legacy CSS imports**: `handsontable.full.min.css` was removed in v17. Use `handsontable/styles/handsontable.min.css` plus a theme file.
+- **Formulas with nested object data**: HyperFormula formulas don't work when `data` is an array of nested objects — use flat objects or arrays of arrays.
+- **ExportFile `columnHeaders` renamed**: In v17.1 the ExportFile plugin's `columnHeaders` option was renamed to `colHeaders` to match the table-level option. Update any `exportAsString` / `exportAsBlob` / `downloadFile` calls that pass `columnHeaders: ...`.
+
+---
+
+## Version Awareness
+
+Handsontable docs are versioned. The latest docs live at `/docs/react-data-grid/` (which redirects
+to the current version). To link to a specific version, use `/docs/17.0/react-data-grid/`.
+
+When helping a user, check which version they are on — breaking changes between major versions are
+common. Point them to the relevant migration guide if they're upgrading.
+
+For the full organized directory of documentation links, read `references/docs-map.md` in this
+skill's folder.
+
+### v17.1 changes (latest, May 2026)
+
+- **New plugins:** DataProvider (server-side row loading via `dataProvider` option), Notification (toast notifications).
+- **NestedHeaders rowspan:** column headers can now span multiple header rows.
+- **ExportFile:** XLSX export added; the `columnHeaders` option was renamed to `colHeaders` (see Common Pitfalls).
+- **Angular wrapper:** modernized for Angular 17–19; simpler setup, fewer deps.
+- **Touch:** long-press now opens the context menu on touch devices.
+- **TypeScript:** `dateFormat` option now accepts `Intl.DateTimeFormatOptions`.
+- No removals or deprecations in v17.1.
+
+### v17.0 Breaking Changes
+
+- Removed legacy wrapper packages (`@handsontable/react`, `@handsontable/angular`). Use
+  `@handsontable/react-wrapper` and `@handsontable/angular-wrapper`.
+- Removed legacy CSS (`handsontable.full.min.css`). Use `handsontable/styles/` imports.
+- Removed core-js from dependencies.
+- Removed the PersistentState plugin.
+- Deprecated bundled HyperFormula (will require separate install in v18).
+- Deprecated numbro.js, Pikaday, moment.js, DOMPurify — use native alternatives.
+
+Migration guide: https://handsontable.com/docs/react-data-grid/migration-from-16.2-to-17.0/

.agents/skills/handsontable/references/docs-map.md

@@ -0,0 +1,231 @@
+# Handsontable Documentation Map
+
+> Last verified: May 2026 · Aligned with Handsontable 17.1.0
+
+Organized link directory for all Handsontable and HyperFormula (in-grid) documentation. Use these
+to point users to the right page. Links default to the React docs; replace `react-data-grid` with
+`javascript-data-grid`, `angular-data-grid`, or prefix with `vue3-` for other frameworks.
+
+## Getting Started
+- Installation: https://handsontable.com/docs/react-data-grid/installation/
+- Demo: https://handsontable.com/docs/react-data-grid/demo/
+- Binding to data: https://handsontable.com/docs/react-data-grid/binding-to-data/
+- Server-side data fetching (DataProvider, v17.1+): https://handsontable.com/docs/react-data-grid/server-side-data-fetching/
+- Saving data: https://handsontable.com/docs/react-data-grid/saving-data/
+- Configuration options guide: https://handsontable.com/docs/react-data-grid/configuration-options/
+- Grid size: https://handsontable.com/docs/react-data-grid/grid-size/
+- Instance methods: https://handsontable.com/docs/react-data-grid/instance-methods/
+- Events and hooks: https://handsontable.com/docs/react-data-grid/events-and-hooks/
+- License key: https://handsontable.com/docs/react-data-grid/license-key/
+- Redux integration: https://handsontable.com/docs/react-data-grid/redux/
+
+## Styling & Themes
+- Themes guide: https://handsontable.com/docs/react-data-grid/themes/
+- Design system (Figma): https://handsontable.com/docs/react-data-grid/handsontable-design-system/
+- Theme customization (CSS vars, tokens): https://handsontable.com/docs/react-data-grid/theme-customization/
+- Legacy style (pre-v15): https://handsontable.com/docs/react-data-grid/legacy-style/
+- Theme Builder tool: https://handsontable.com/theme-builder
+- Figma Theme Generator: https://github.com/handsontable/handsontable-figma
+
+## Columns
+- HotColumn component (React): https://handsontable.com/docs/react-data-grid/hot-column/
+- Column headers: https://handsontable.com/docs/react-data-grid/column-header/
+- Column groups (nested headers): https://handsontable.com/docs/react-data-grid/column-groups/
+- Column hiding: https://handsontable.com/docs/react-data-grid/column-hiding/
+- Column moving: https://handsontable.com/docs/react-data-grid/column-moving/
+- Column freezing: https://handsontable.com/docs/react-data-grid/column-freezing/
+- Column widths: https://handsontable.com/docs/react-data-grid/column-width/
+- Column summary: https://handsontable.com/docs/react-data-grid/column-summary/
+- Column virtualization: https://handsontable.com/docs/react-data-grid/column-virtualization/
+- Column menu (dropdown): https://handsontable.com/docs/react-data-grid/column-menu/
+- Column filter: https://handsontable.com/docs/react-data-grid/column-filter/
+
+## Rows
+- Row headers: https://handsontable.com/docs/react-data-grid/row-header/
+- Row parent-child (nested rows): https://handsontable.com/docs/react-data-grid/row-parent-child/
+- Row hiding: https://handsontable.com/docs/react-data-grid/row-hiding/
+- Row moving: https://handsontable.com/docs/react-data-grid/row-moving/
+- Row freezing: https://handsontable.com/docs/react-data-grid/row-freezing/
+- Row heights: https://handsontable.com/docs/react-data-grid/row-height/
+- Row virtualization: https://handsontable.com/docs/react-data-grid/row-virtualization/
+- Rows sorting: https://handsontable.com/docs/react-data-grid/rows-sorting/
+- Rows pagination: https://handsontable.com/docs/react-data-grid/rows-pagination/
+- Row trimming: https://handsontable.com/docs/react-data-grid/row-trimming/
+- Row pre-populating: https://handsontable.com/docs/react-data-grid/row-prepopulating/
+
+## Cell Features
+- Clipboard (copy/paste): https://handsontable.com/docs/react-data-grid/basic-clipboard/
+- Selection: https://handsontable.com/docs/react-data-grid/selection/
+- Merge cells: https://handsontable.com/docs/react-data-grid/merge-cells/
+- Conditional formatting: https://handsontable.com/docs/react-data-grid/conditional-formatting/
+- Text alignment: https://handsontable.com/docs/react-data-grid/text-alignment/
+- Disabled cells: https://handsontable.com/docs/react-data-grid/disabled-cells/
+- Comments: https://handsontable.com/docs/react-data-grid/comments/
+- Autofill values: https://handsontable.com/docs/react-data-grid/autofill-values/
+- Formatting cells: https://handsontable.com/docs/react-data-grid/formatting-cells/
+
+## Cell Functions
+- Cell functions overview: https://handsontable.com/docs/react-data-grid/cell-function/
+- Cell renderer: https://handsontable.com/docs/react-data-grid/cell-renderer/
+- Cell editor: https://handsontable.com/docs/react-data-grid/cell-editor/
+- Cell validator: https://handsontable.com/docs/react-data-grid/cell-validator/
+- Custom cells (v17+): https://handsontable.com/docs/react-data-grid/custom-cells/
+
+## Cell Types
+- Cell type overview: https://handsontable.com/docs/react-data-grid/cell-type/
+- Numeric: https://handsontable.com/docs/react-data-grid/numeric-cell-type/
+- Date: https://handsontable.com/docs/react-data-grid/date-cell-type/
+- Time: https://handsontable.com/docs/react-data-grid/time-cell-type/
+- Checkbox: https://handsontable.com/docs/react-data-grid/checkbox-cell-type/
+- Select: https://handsontable.com/docs/react-data-grid/select-cell-type/
+- Dropdown: https://handsontable.com/docs/react-data-grid/dropdown-cell-type/
+- Autocomplete: https://handsontable.com/docs/react-data-grid/autocomplete-cell-type/
+- MultiSelect (v17+): https://handsontable.com/docs/react-data-grid/multiselect-cell-type/
+- Password: https://handsontable.com/docs/react-data-grid/password-cell-type/
+- Handsontable (nested grid): https://handsontable.com/docs/react-data-grid/handsontable-cell-type/
+
+## Formulas (HyperFormula in Handsontable)
+- Formula calculation guide: https://handsontable.com/docs/react-data-grid/formula-calculation/
+- Formulas plugin API: https://handsontable.com/docs/react-data-grid/api/formulas/
+- HyperFormula built-in functions list: https://hyperformula.handsontable.com/docs/guide/built-in-functions.html
+- HyperFormula configuration options: https://hyperformula.handsontable.com/docs/guide/configuration-options.html
+- HyperFormula custom functions: https://hyperformula.handsontable.com/docs/guide/custom-functions.html
+- HyperFormula named expressions: https://hyperformula.handsontable.com/docs/guide/cell-references.html#relative-references
+- HyperFormula license key: https://hyperformula.handsontable.com/docs/guide/license-key.html
+
+## Navigation
+- Keyboard shortcuts: https://handsontable.com/docs/react-data-grid/keyboard-shortcuts/
+- Custom shortcuts: https://handsontable.com/docs/react-data-grid/custom-shortcuts/
+- Focus scopes: https://handsontable.com/docs/react-data-grid/focus-scopes/
+- Searching values: https://handsontable.com/docs/react-data-grid/searching-values/
+
+## Accessibility
+- Accessibility guide: https://handsontable.com/docs/react-data-grid/accessibility/
+
+## Menus & Accessories
+- Context menu: https://handsontable.com/docs/react-data-grid/context-menu/
+- Undo and redo: https://handsontable.com/docs/react-data-grid/undo-redo/
+- Icon pack: https://handsontable.com/docs/react-data-grid/icon-pack/
+- Export to CSV: https://handsontable.com/docs/react-data-grid/export-to-csv/
+- Export to Excel/XLSX (v17.1+): https://handsontable.com/docs/react-data-grid/export-to-excel/
+- Notification (v17.1+): https://handsontable.com/docs/react-data-grid/notification/
+- Empty data state: https://handsontable.com/docs/react-data-grid/empty-data-state/
+
+## Dialog & Loading
+- Dialog: https://handsontable.com/docs/react-data-grid/dialog/
+- Loading indicator: https://handsontable.com/docs/react-data-grid/loading/
+
+## Internationalization
+- Language: https://handsontable.com/docs/react-data-grid/language/
+- Locale: https://handsontable.com/docs/react-data-grid/locale/
+- Layout direction (RTL/LTR): https://handsontable.com/docs/react-data-grid/layout-direction/
+- IME support: https://handsontable.com/docs/react-data-grid/ime-support/
+
+## Tools & Building
+- Modules (tree-shaking): https://handsontable.com/docs/react-data-grid/modules/
+- Custom plugins: https://handsontable.com/docs/react-data-grid/custom-plugins/
+- Custom builds: https://handsontable.com/docs/react-data-grid/custom-builds/
+- Testing: https://handsontable.com/docs/react-data-grid/testing/
+
+## Optimization
+- Batch operations: https://handsontable.com/docs/react-data-grid/batch-operations/
+- Performance: https://handsontable.com/docs/react-data-grid/performance/
+- Bundle size: https://handsontable.com/docs/react-data-grid/bundle-size/
+
+## Security
+- Security guide: https://handsontable.com/docs/react-data-grid/security/
+
+## API Reference
+- API overview: https://handsontable.com/docs/react-data-grid/api/
+- Core (instance methods): https://handsontable.com/docs/react-data-grid/api/core/
+- Hooks (all events): https://handsontable.com/docs/react-data-grid/api/hooks/
+- Configuration options (all props): https://handsontable.com/docs/react-data-grid/api/options/
+- Plugins index: https://handsontable.com/docs/react-data-grid/api/plugins/
+
+### Individual Plugin APIs
+- AutoColumnSize: https://handsontable.com/docs/react-data-grid/api/auto-column-size/
+- AutoRowSize: https://handsontable.com/docs/react-data-grid/api/auto-row-size/
+- Autofill: https://handsontable.com/docs/react-data-grid/api/autofill/
+- BindRowsWithHeaders: https://handsontable.com/docs/react-data-grid/api/bind-rows-with-headers/
+- CollapsibleColumns: https://handsontable.com/docs/react-data-grid/api/collapsible-columns/
+- ColumnSorting: https://handsontable.com/docs/react-data-grid/api/column-sorting/
+- ColumnSummary: https://handsontable.com/docs/react-data-grid/api/column-summary/
+- Comments: https://handsontable.com/docs/react-data-grid/api/comments/
+- ContextMenu: https://handsontable.com/docs/react-data-grid/api/context-menu/
+- CopyPaste: https://handsontable.com/docs/react-data-grid/api/copy-paste/
+- CustomBorders: https://handsontable.com/docs/react-data-grid/api/custom-borders/
+- DataProvider (v17.1+): https://handsontable.com/docs/react-data-grid/api/data-provider/
+- Dialog: https://handsontable.com/docs/react-data-grid/api/dialog/
+- DragToScroll: https://handsontable.com/docs/react-data-grid/api/drag-to-scroll/
+- DropdownMenu: https://handsontable.com/docs/react-data-grid/api/dropdown-menu/
+- EmptyDataState: https://handsontable.com/docs/react-data-grid/api/empty-data-state/
+- ExportFile: https://handsontable.com/docs/react-data-grid/api/export-file/
+- Filters: https://handsontable.com/docs/react-data-grid/api/filters/
+- Formulas: https://handsontable.com/docs/react-data-grid/api/formulas/
+- HiddenColumns: https://handsontable.com/docs/react-data-grid/api/hidden-columns/
+- HiddenRows: https://handsontable.com/docs/react-data-grid/api/hidden-rows/
+- Loading: https://handsontable.com/docs/react-data-grid/api/loading/
+- ManualColumnFreeze: https://handsontable.com/docs/react-data-grid/api/manual-column-freeze/
+- ManualColumnMove: https://handsontable.com/docs/react-data-grid/api/manual-column-move/
+- ManualColumnResize: https://handsontable.com/docs/react-data-grid/api/manual-column-resize/
+- ManualRowMove: https://handsontable.com/docs/react-data-grid/api/manual-row-move/
+- ManualRowResize: https://handsontable.com/docs/react-data-grid/api/manual-row-resize/
+- MergeCells: https://handsontable.com/docs/react-data-grid/api/merge-cells/
+- MultiColumnSorting: https://handsontable.com/docs/react-data-grid/api/multi-column-sorting/
+- NestedHeaders: https://handsontable.com/docs/react-data-grid/api/nested-headers/
+- NestedRows: https://handsontable.com/docs/react-data-grid/api/nested-rows/
+- Notification (v17.1+): https://handsontable.com/docs/react-data-grid/api/notification/
+- Pagination: https://handsontable.com/docs/react-data-grid/api/pagination/
+- Search: https://handsontable.com/docs/react-data-grid/api/search/
+- StretchColumns: https://handsontable.com/docs/react-data-grid/api/stretch-columns/
+- TrimRows: https://handsontable.com/docs/react-data-grid/api/trim-rows/
+- UndoRedo: https://handsontable.com/docs/react-data-grid/api/undo-redo/
+
+## Recipes (new in v17)
+- Recipes index: https://handsontable.com/docs/react-data-grid/recipes/
+- Load data from a REST API (DataProvider, v17.1+): https://handsontable.com/docs/react-data-grid/recipes/data-management/load-data-rest-api/
+
+## Upgrade & Migration
+- Changelog: https://handsontable.com/docs/react-data-grid/changelog/
+- Versioning policy: https://handsontable.com/docs/react-data-grid/versioning-policy/
+- Deprecation policy: https://handsontable.com/docs/react-data-grid/deprecation-policy/
+- Long Term Support (LTS): https://handsontable.com/docs/react-data-grid/long-term-support/
+- 16.2 → 17.0 migration: https://handsontable.com/docs/react-data-grid/migration-from-16.2-to-17.0/
+- 16.0 → 16.1 migration: https://handsontable.com/docs/react-data-grid/migration-from-16.0-to-16.1/
+- 15.3 → 16.0 migration: https://handsontable.com/docs/react-data-grid/migration-from-15.3-to-16.0/
+- 14.6 → 15.0 migration: https://handsontable.com/docs/react-data-grid/migration-from-14.6-to-15.0/
+
+## Other Framework Installation
+- JavaScript: https://handsontable.com/docs/javascript-data-grid/installation/
+- Angular: https://handsontable.com/docs/angular-data-grid/installation/
+- Vue 3: https://handsontable.com/docs/react-data-grid/vue3-installation/
+
+## SSR Examples (CodeSandbox)
+- Next.js: https://codesandbox.io/p/sandbox/kwnjph?file=https://handsontable.com/codesandbox-vm?example-dir=next.js&handsontable-version=17.1preview=true
+- Astro: https://codesandbox.io/p/sandbox/gnqcwn?file=https://handsontable.com/codesandbox-vm?example-dir=astro&handsontable-version=17.1preview=true
+- Remix: https://codesandbox.io/p/sandbox/njcjlq?file=https://handsontable.com/codesandbox-vm?example-dir=remix&handsontable-version=17.1preview=true
+- Nuxt: https://codesandbox.io/p/sandbox/r7qsjc?file=https://handsontable.com/codesandbox-vm?example-dir=nuxt&handsontable-version=17.1preview=true
+
+## CDN Links (jsDelivr) — latest
+- JS (full bundle): https://cdn.jsdelivr.net/npm/handsontable/dist/handsontable.full.min.js
+- Base CSS: https://cdn.jsdelivr.net/npm/handsontable/styles/handsontable.min.css
+- Theme Main: https://cdn.jsdelivr.net/npm/handsontable/styles/ht-theme-main.min.css
+- Theme Horizon: https://cdn.jsdelivr.net/npm/handsontable/styles/ht-theme-horizon.min.css
+- Theme Classic: https://cdn.jsdelivr.net/npm/handsontable/styles/ht-theme-classic.min.css
+- React wrapper: https://cdn.jsdelivr.net/npm/@handsontable/react-wrapper/dist/react-handsontable.min.js
+- HyperFormula: https://cdn.jsdelivr.net/npm/hyperformula/dist/hyperformula.full.min.js
+
+Pin versions by adding `@17.1` after the package name (e.g., `handsontable@17.1`).
+
+## Package Registries
+- npm: https://www.npmjs.com/package/handsontable
+- NuGet: https://www.nuget.org/packages/handsontable
+
+## Community & Support
+- Developer Forum: https://forum.handsontable.com/
+- GitHub Issues: https://github.com/handsontable/handsontable/issues
+- Stack Overflow: https://stackoverflow.com/tags/handsontable
+- Commercial support: support@handsontable.com
+- Contact form: https://handsontable.com/contact
+- Blog / Release Notes: https://handsontable.com/blog/categories/release-notes
+- Download page: https://handsontable.com/download

.agents/skills/hyperformula/README.md

@@ -0,0 +1,85 @@
+# @handsontable/hyperformula-skill
+
+An agent skill for [**HyperFormula**](https://hyperformula.handsontable.com) — the headless, open-source TypeScript spreadsheet calculation engine. It gives any AI coding agent deep, task-oriented knowledge of HyperFormula so the agent can help you integrate, configure, and debug the engine faster.
+
+This package is the npm distribution of the `hyperformula` skill maintained in [`handsontable/handsontable-skills`](https://github.com/handsontable/handsontable-skills). The package version tracks the HyperFormula product version the skill targets (e.g. `3.3.0` targets HyperFormula 3.3.0).
+
+## What's in the package
+
+A self-contained skill — plain markdown, no runtime dependencies:
+
+```
+SKILL.md        ← entry point: concepts, routing, and a docs map (YAML frontmatter + body)
+references/     ← task-oriented deep-dives the agent reads on demand
+```
+
+`SKILL.md` follows the [Agent Skills](https://claude.com/blog/skills) layout (a YAML frontmatter block with `name`/`description`, followed by markdown instructions). Any agent that can load a skill — or simply read a folder of markdown instructions — can use it.
+
+## Install
+
+```bash
+npm install @handsontable/hyperformula-skill
+```
+
+The installed package lives at `node_modules/@handsontable/hyperformula-skill`. Resolve that path programmatically with:
+
+```bash
+node -p "require.resolve('@handsontable/hyperformula-skill/SKILL.md')"
+```
+
+Then make the skill available to your agent using whichever of the following matches it:
+
+### Claude Code
+
+Copy the package into a skills directory. User scope (available in every project):
+
+```bash
+cp -r node_modules/@handsontable/hyperformula-skill ~/.claude/skills/hyperformula
+```
+
+Or project scope, from your project root:
+
+```bash
+cp -r node_modules/@handsontable/hyperformula-skill .claude/skills/hyperformula
+```
+
+### Claude API
+
+Upload the package contents (`SKILL.md` + `references/`) to the [Skills API](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
+
+### OpenAI Codex
+
+Codex discovers [skills](https://developers.openai.com/codex/skills) as folders containing a `SKILL.md`, under `~/.agents/skills` (available in every repo) or `.agents/skills` in a repo (checked in for your team). Copy the package into one of those locations:
+
+```bash
+# User scope — available in every repo
+cp -r node_modules/@handsontable/hyperformula-skill ~/.agents/skills/hyperformula
+
+# Repo scope — from your project root
+cp -r node_modules/@handsontable/hyperformula-skill .agents/skills/hyperformula
+```
+
+Codex also follows symlinked skill folders, so you can instead link the installed package and let `npm install` keep it current:
+
+```bash
+ln -s "$PWD/node_modules/@handsontable/hyperformula-skill" ~/.agents/skills/hyperformula
+```
+
+### Any other agent
+
+Most coding agents support a skills, rules, or knowledge directory. Copy (or symlink) the package folder into it, for example:
+
+```bash
+# Replace <agent-skills-dir> with your agent's skills/knowledge directory
+cp -r node_modules/@handsontable/hyperformula-skill <agent-skills-dir>/hyperformula
+```
+
+If your agent reads a single instruction file rather than a folder, point it at `SKILL.md`; it links the files under `references/` so the agent can pull them in as needed. For RAG / vector-store setups, ingest `SKILL.md` together with every file under `references/` (the repository also publishes a pre-flattened `hyperformula-rag.md` for this case).
+
+## Other distribution formats
+
+The same skill source is also shipped as a drag-and-drop `.zip` (Cowork / Claude.ai web), a flattened `-rag.md` doc (RAG / vector stores), and a Claude Code plugin marketplace entry. See the [repository README](https://github.com/handsontable/handsontable-skills#readme) for details.
+
+## License
+
+MIT — see the [repository](https://github.com/handsontable/handsontable-skills/blob/main/LICENSE.txt). HyperFormula itself is separately licensed (GPLv3 or commercial); see the [licensing guide](https://hyperformula.handsontable.com/docs/guide/licensing.html).

.agents/skills/hyperformula/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: hyperformula
+description: >
+  Use this skill when the user works with HyperFormula (HF) — a headless,
+  open-source TypeScript spreadsheet calculation engine. Use it when the user:
+  mentions HyperFormula or HF; wants to integrate Excel-like formulas into a
+  JS/TS app; evaluate formulas programmatically in a browser or Node.js;
+  simulate spreadsheet or Excel calculation behavior server-side; run
+  calculations over data parsed from XLSX files (e.g. via SheetJS) in code;
+  build a pricing engine, financial model, or what-if analysis in code; define
+  custom spreadsheet functions or named expressions outside of a UI context. Do
+  NOT use this skill for: general Excel questions unrelated to HF; general
+  Google Sheets questions; generic spreadsheet formula-syntax questions outside
+  an HF context; formulas used inside Handsontable (use the "handsontable"
+  skill instead).
+---
+
+# HyperFormula
+
+HyperFormula is a **headless, open-source TypeScript spreadsheet calculation engine** for embedding spreadsheet logic in any JavaScript/TypeScript application (browser or Node.js). ~420 built-in functions, dependency graph, undo/redo, i18n (17 languages). Dual-licensed: GPLv3 or commercial.
+
+- Docs: https://hyperformula.handsontable.com/
+- npm: https://www.npmjs.com/package/hyperformula
+- GitHub: https://github.com/handsontable/hyperformula
+
+## Where to go next
+
+Task-oriented references in `references/` (open the one that matches what the user is doing):
+
+- [`getting-started.md`](references/getting-started.md) — how to install, create an instance (`buildFromArray` / `buildFromSheets` / `buildEmpty`), and work with cell addresses. Open this for onboarding questions and first-run errors.
+- [`api-quickref.md`](references/api-quickref.md) — runnable examples for CRUD, rows/columns, sheets, exporting data, batching, named expressions, events, undo/redo, clipboard. Open this when implementing or debugging HF API calls.
+- [`custom-functions.md`](references/custom-functions.md) — extending HyperFormula via `FunctionPlugin`: minimal plugin, argument types, volatile functions, range arguments, returning arrays, error handling, aliases, localized names. Open this when adding or debugging custom spreadsheet functions.
+- [`configuration.md`](references/configuration.md) — `ConfigParams` options, Excel-compatibility preset, Google-Sheets preset, and config-related pitfalls (separator collisions, Node ICU, `precisionRounding` change in v3). Open this when tuning behavior or diagnosing locale issues.
+- [`vue3.md`](references/vue3.md) — Vue 3 integration: `markRaw` requirement, Composition API, Pinia/Vuex stores, `destroy()` on unmount. Open this when embedding HF in a Vue 3 app.
+- [`error-handling.md`](references/error-handling.md) — inspecting `CellError`, `ErrorType` enum, `getCellValueDetailedType`, common error causes (`#NAME?`, `#CYCLE!`, `#REF!`, …). Open this when a cell returns an error or you need to branch on result type.
+- [`general-pitfalls.md`](references/general-pitfalls.md) — cross-cutting gotchas: `destroy()` lifecycle, forcing literal strings, Excel-parity caveats, hard limits. Open this when results look wrong or memory grows unboundedly.
+
+Below this section is the **Documentation map** — the canonical directory of links to the official HyperFormula docs. Use it when pointing the user to authoritative material.
+
+## Documentation map
+
+All links resolve to `hyperformula.handsontable.com` unless noted.
+
+### Introduction
+- Welcome / Homepage: https://hyperformula.handsontable.com/
+- Demo: https://hyperformula.handsontable.com/docs/guide/demo.html
+
+### Overview
+- Quality (test coverage, CI): https://hyperformula.handsontable.com/docs/guide/quality.html
+- Supported browsers: https://hyperformula.handsontable.com/docs/guide/supported-browsers.html
+- Dependencies: https://hyperformula.handsontable.com/docs/guide/dependencies.html
+- Licensing (GPLv3 vs commercial): https://hyperformula.handsontable.com/docs/guide/licensing.html
+- Support: https://hyperformula.handsontable.com/docs/guide/support.html
+
+### Getting Started
+- Client-side installation: https://hyperformula.handsontable.com/docs/guide/client-side-installation.html
+- Server-side installation (Node.js): https://hyperformula.handsontable.com/docs/guide/server-side-installation.html
+- Basic usage: https://hyperformula.handsontable.com/docs/guide/basic-usage.html
+- Advanced usage: https://hyperformula.handsontable.com/docs/guide/advanced-usage.html
+- Configuration options guide: https://hyperformula.handsontable.com/docs/guide/configuration-options.html
+- License key setup: https://hyperformula.handsontable.com/docs/guide/license-key.html
+
+### Framework Integration
+- React: https://hyperformula.handsontable.com/docs/guide/integration-with-react.html
+- Vue: https://hyperformula.handsontable.com/docs/guide/integration-with-vue.html
+- Angular: https://hyperformula.handsontable.com/docs/guide/integration-with-angular.html
+- Svelte: https://hyperformula.handsontable.com/docs/guide/integration-with-svelte.html
+
+### Data Operations
+- Basic operations (CRUD): https://hyperformula.handsontable.com/docs/guide/basic-operations.html
+- Batch operations: https://hyperformula.handsontable.com/docs/guide/batch-operations.html
+- Clipboard operations: https://hyperformula.handsontable.com/docs/guide/clipboard-operations.html
+- Undo-redo: https://hyperformula.handsontable.com/docs/guide/undo-redo.html
+- Sorting data: https://hyperformula.handsontable.com/docs/guide/sorting-data.html
+
+### Formulas
+- Specifications and limits: https://hyperformula.handsontable.com/docs/guide/specifications-and-limits.html
+- Cell references (relative, absolute, mixed, cross-sheet): https://hyperformula.handsontable.com/docs/guide/cell-references.html
+- Types of values: https://hyperformula.handsontable.com/docs/guide/types-of-values.html
+- Types of errors: https://hyperformula.handsontable.com/docs/guide/types-of-errors.html
+- Types of operators: https://hyperformula.handsontable.com/docs/guide/types-of-operators.html
+- Order of precedence: https://hyperformula.handsontable.com/docs/guide/order-of-precendece.html
+- Built-in functions (full list, ~400): https://hyperformula.handsontable.com/docs/guide/built-in-functions.html
+- Volatile functions: https://hyperformula.handsontable.com/docs/guide/volatile-functions.html
+- Named expressions: https://hyperformula.handsontable.com/docs/guide/named-expressions.html
+- Array formulas / ARRAYFORMULA: https://hyperformula.handsontable.com/docs/guide/arrays.html
+
+### Internationalization
+- i18n features (17 languages): https://hyperformula.handsontable.com/docs/guide/i18n-features.html
+- Localizing function names: https://hyperformula.handsontable.com/docs/guide/localizing-functions.html
+- Date and time handling: https://hyperformula.handsontable.com/docs/guide/date-and-time-handling.html
+
+### Compatibility
+- Microsoft Excel compatibility: https://hyperformula.handsontable.com/docs/guide/compatibility-with-microsoft-excel.html
+- Google Sheets compatibility: https://hyperformula.handsontable.com/docs/guide/compatibility-with-google-sheets.html
+- Runtime differences (Excel & Sheets): https://hyperformula.handsontable.com/docs/guide/list-of-differences.html
+
+### Advanced Topics
+- Key concepts (AST, dependency graph, evaluation): https://hyperformula.handsontable.com/docs/guide/key-concepts.html
+- Dependency graph: https://hyperformula.handsontable.com/docs/guide/dependency-graph.html
+- Building & testing from source: https://hyperformula.handsontable.com/docs/guide/building.html
+- Custom functions (FunctionPlugin): https://hyperformula.handsontable.com/docs/guide/custom-functions.html
+- Performance: https://hyperformula.handsontable.com/docs/guide/performance.html
+- Known limitations: https://hyperformula.handsontable.com/docs/guide/known-limitations.html
+- File import: https://hyperformula.handsontable.com/docs/guide/file-import.html
+
+### Upgrade & Migration
+- Release notes / Changelog: https://hyperformula.handsontable.com/docs/guide/release-notes.html
+- 0.6 → 1.0 migration: https://hyperformula.handsontable.com/docs/guide/migration-from-0.6-to-1.0.html
+- 1.x → 2.0 migration: https://hyperformula.handsontable.com/docs/guide/migration-from-1.x-to-2.0.html
+- 2.x → 3.0 migration: https://hyperformula.handsontable.com/docs/guide/migration-from-2.x-to-3.0.html
+
+### API Reference
+- API overview: https://hyperformula.handsontable.com/docs/api/
+- HyperFormula class (all methods): https://hyperformula.handsontable.com/docs/api/classes/hyperformula.html
+- ConfigParams interface (all options): https://hyperformula.handsontable.com/docs/api/interfaces/configparams.html
+- Listeners interface (all events): https://hyperformula.handsontable.com/docs/api/interfaces/listeners.html
+
+### npm
+- npm page: https://www.npmjs.com/package/hyperformula
+
+### Community & Support
+- GitHub repo: https://github.com/handsontable/hyperformula
+- GitHub Issues: https://github.com/handsontable/hyperformula/issues
+- GitHub Discussions: https://github.com/handsontable/hyperformula/discussions
+- Developer Forum: https://forum.handsontable.com/
+- Commercial support: support@handsontable.com
+- Sales (commercial license): sales@handsontable.com
+- Contact form: https://handsontable.com/contact
+
+---
+
+> **Last updated: 2026-05-20 · Aligned with HyperFormula 3.3.0.**
+> If the user is on a newer release, confirm API shape against the latest docs (see the **Release notes** link above) before relying on this file.

.agents/skills/hyperformula/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@handsontable/hyperformula-skill",
+  "version": "3.3.0",
+  "description": "Agent skill for HyperFormula — the headless, open-source TypeScript spreadsheet calculation engine. Teaches AI coding agents how to integrate, configure, and debug HyperFormula.",
+  "license": "MIT",
+  "author": "Handsontable <hello@handsontable.com> (https://handsontable.com)",
+  "homepage": "https://github.com/handsontable/handsontable-skills#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/handsontable/handsontable-skills.git",
+    "directory": "skills/hyperformula"
+  },
+  "bugs": {
+    "url": "https://github.com/handsontable/handsontable-skills/issues"
+  },
+  "keywords": [
+    "agent-skill",
+    "claude-skill",
+    "claude",
+    "anthropic",
+    "ai",
+    "hyperformula",
+    "spreadsheet",
+    "formula-engine",
+    "handsontable"
+  ],
+  "files": [
+    "SKILL.md",
+    "references/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

.agents/skills/hyperformula/references/api-quickref.md

@@ -0,0 +1,147 @@
+# API Quick Reference
+
+Runnable examples for the most-used HyperFormula APIs. Authoritative docs:
+- Basic operations: https://hyperformula.handsontable.com/docs/guide/basic-operations.html
+- Batch operations: https://hyperformula.handsontable.com/docs/guide/batch-operations.html
+- Named expressions: https://hyperformula.handsontable.com/docs/guide/named-expressions.html
+- Clipboard operations: https://hyperformula.handsontable.com/docs/guide/clipboard-operations.html
+- Undo-redo: https://hyperformula.handsontable.com/docs/guide/undo-redo.html
+- Sorting data: https://hyperformula.handsontable.com/docs/guide/sorting-data.html
+- HyperFormula class (all methods): https://hyperformula.handsontable.com/docs/api/classes/hyperformula.html
+- Listeners (all events): https://hyperformula.handsontable.com/docs/api/interfaces/listeners.html
+
+## CRUD
+
+```ts
+// Write: string, number, or formula
+hf.setCellContents({ sheet: 0, col: 0, row: 0 }, 'Hello');
+hf.setCellContents({ sheet: 0, col: 1, row: 0 }, '=A1 & " World"');
+
+// Read
+hf.getCellValue({ sheet: 0, col: 1, row: 0 });    // computed result
+hf.getCellFormula({ sheet: 0, col: 1, row: 0 });  // '=A1 & " World"'
+hf.getCellType({ sheet: 0, col: 0, row: 0 });     // CellType.FORMULA | VALUE | EMPTY
+```
+
+## Rows and columns
+
+Second arg is `[startIndex, count]`, not a list of indexes.
+
+```ts
+hf.addRows(sheetId, [rowIndex, numberOfRows]);
+hf.removeRows(sheetId, [rowIndex, numberOfRows]);
+hf.addColumns(sheetId, [colIndex, numberOfColumns]);
+hf.removeColumns(sheetId, [colIndex, numberOfColumns]);
+```
+
+## Sheets
+
+```ts
+hf.addSheet('NewSheet');
+hf.removeSheet(sheetId);
+hf.renameSheet(sheetId, 'BetterName');
+hf.countSheets();
+hf.getSheetName(sheetId);
+hf.getSheetId('SheetName');
+hf.getSheetDimensions(sheetId); // → { width, height }
+```
+
+## Export data
+
+```ts
+hf.getSheetValues(sheetId);        // computed values as 2D array
+hf.getSheetSerialized(sheetId);    // formulas/raw values as 2D array
+hf.getAllSheetsValues();            // { SheetName: values[][] }
+hf.getAllSheetsSerialized();        // { SheetName: formulas[][] }
+```
+
+## Batch operations
+
+Every `setCellContents` call triggers a full dependency-graph recalculation. Always batch when writing more than one cell.
+
+```ts
+// Preferred: batch() — returns ExportedChange[]
+const changes = hf.batch(() => {
+  hf.setCellContents({ sheet: 0, col: 0, row: 0 }, '100');
+  hf.setCellContents({ sheet: 0, col: 0, row: 1 }, '200');
+  hf.addRows(0, [2, 1]);
+});
+// `changes` contains all cells that were recalculated.
+
+// For bulk imports (value writes only):
+hf.suspendEvaluation();
+// ... hundreds of setCellContents calls ...
+hf.resumeEvaluation();  // single recalc
+
+// PITFALL: structural ops (addRows/moveRows/...) during suspendEvaluation
+// have degraded performance. Use batch() when mixing structural + value writes.
+```
+
+## Sorting
+
+`setRowOrder` takes a **permutation array**, not a comparator. Compute the new index sequence externally, then pass it in.
+
+```ts
+// Sort rows by the value in column 0
+const rowCount = hf.getSheetDimensions(0).height;
+const indexes = Array.from({ length: rowCount }, (_, i) => i);
+indexes.sort((a, b) => {
+  const va = hf.getCellValue({ sheet: 0, col: 0, row: a }) as number;
+  const vb = hf.getCellValue({ sheet: 0, col: 0, row: b }) as number;
+  return va - vb;
+});
+hf.setRowOrder(0, indexes); // e.g. [2, 0, 1, 3]
+```
+
+## Named expressions
+
+Reusable names for values or formulas. Can be global or scoped to a sheet (local shadows global).
+
+```ts
+hf.addNamedExpression('TAX_RATE', '0.21');
+hf.addNamedExpression('TOTAL_REVENUE', '=SUM(Revenue!A:A)');
+
+hf.setCellContents({ sheet: 0, col: 0, row: 0 }, '=1000 * TAX_RATE');
+
+hf.listNamedExpressions(); // all registered names
+```
+
+## Custom functions
+
+See [custom-functions.md](custom-functions.md) — `FunctionPlugin`, argument types, volatile functions, range arguments, returning arrays, error handling, aliases, localized names.
+
+## Events
+
+Subscribe via `.on()` on the instance. Full list: https://hyperformula.handsontable.com/docs/api/interfaces/listeners.html
+
+```ts
+hf.on('valuesUpdated', (changes) => {
+  changes.forEach((c) => console.log(c.address, c.newValue));
+});
+
+hf.on('sheetAdded', (addedSheetName) => { /* ... */ });
+hf.on('sheetRemoved', (removedSheetName, removedSheetData) => { /* ... */ });
+hf.on('sheetRenamed', (oldName, newName) => { /* ... */ });
+```
+
+## Undo / redo
+
+```ts
+hf.undo();
+hf.redo();
+hf.isThereSomethingToUndo();
+hf.isThereSomethingToRedo();
+hf.clearUndoStack();
+```
+
+Configure depth via `undoLimit` in `ConfigParams` (see [configuration.md](configuration.md)).
+
+## Clipboard
+
+```ts
+hf.copy({ start: { sheet: 0, col: 0, row: 0 }, end: { sheet: 0, col: 1, row: 1 } });
+hf.cut ({ start: { sheet: 0, col: 0, row: 0 }, end: { sheet: 0, col: 1, row: 1 } });
+hf.paste({ sheet: 0, col: 5, row: 5 });
+hf.isClipboardEmpty();
+hf.clearClipboard();
+```

.agents/skills/hyperformula/references/configuration.md

@@ -0,0 +1,92 @@
+# Configuration
+
+`ConfigParams` + compatibility presets + config-specific pitfalls. Authoritative docs:
+- Configuration options guide: https://hyperformula.handsontable.com/docs/guide/configuration-options.html
+- ConfigParams (all options): https://hyperformula.handsontable.com/docs/api/interfaces/configparams.html
+- Excel compatibility: https://hyperformula.handsontable.com/docs/guide/compatibility-with-microsoft-excel.html
+- Google Sheets compatibility: https://hyperformula.handsontable.com/docs/guide/compatibility-with-google-sheets.html
+
+## ConfigParams highlights
+
+Pass as the second argument to any factory method.
+
+```ts
+const hf = HyperFormula.buildEmpty({
+  licenseKey: 'gpl-v3',           // required — 'gpl-v3' for open source
+  precisionRounding: 10,          // decimal rounding precision (default 10; was 14 before v3)
+  functionArgSeparator: ',',      // separator between function arguments
+  dateFormats: ['DD/MM/YYYY', 'DD-MM-YYYY'],
+  nullDate: { year: 1900, month: 1, day: 1 },
+  leapYear1900: false,            // Excel bug compat: treat 1900 as leap year
+  maxRows: 40000,                 // max rows per sheet (default 40000)
+  maxColumns: 18278,              // max columns per sheet (default 18278 = 'ZZZ')
+  undoLimit: 20,                  // undo history depth
+  maxPendingLazyTransformations: 1000, // v3.3+ — cap accumulated lazy transformations before cleanup
+});
+```
+
+## Excel compatibility preset
+
+```ts
+const hf = HyperFormula.buildEmpty({
+  licenseKey: 'gpl-v3',
+  useArrayArithmetic: true,
+  useWildcards: true,
+  evaluateNullToZero: true,
+  leapYear1900: true,     // Excel's intentional 1900 leap-year bug
+  ignoreWhiteSpace: 'any',
+  caseSensitive: false,
+  accentSensitive: true,
+});
+```
+
+## Google Sheets compatibility preset
+
+Defaults already match Google Sheets behavior (`leapYear1900: false`, `useArrayArithmetic: false`).
+
+```ts
+const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
+```
+
+## Config-specific pitfalls
+
+### Vue 3
+
+Vue 3 requires wrapping the instance with `markRaw` — see [vue3.md](vue3.md) for the full integration guide (React / Angular / Svelte need no special handling).
+
+### `functionArgSeparator` vs `thousandSeparator` collision
+
+These two options **cannot share a character**. European locales that use `,` as thousand separator must change the argument separator:
+
+```ts
+const hf = HyperFormula.buildEmpty({
+  licenseKey: 'gpl-v3',
+  thousandSeparator: ',',
+  decimalSeparator: '.',
+  functionArgSeparator: ';',  // must differ from thousandSeparator
+});
+```
+
+### Node.js must have full ICU
+
+String comparisons (used in `MATCH`, `VLOOKUP`, sorting) can silently produce wrong results on Node.js < 13 or builds without full ICU. Verify at startup:
+
+```ts
+// Must report 'full' (or a detailed ICU version), not 'small'.
+console.log(process.versions.icu);
+```
+
+### Tuning `maxPendingLazyTransformations` (v3.3+)
+
+HyperFormula defers some structural transformations (row/column insertions, moves) and applies them lazily. In long-lived instances with heavy mutation throughput — bulk imports, frequent undo/redo, scripted batch edits — the pending queue can grow before cleanup. v3.3 fixed the unbounded-growth leak; this option lets you cap the queue explicitly. Lower values trade memory for more frequent flush work; the default is suitable for typical UI workloads.
+
+### `precisionRounding` default changed in v3
+
+Before v3 the default was `14`. It is now `10`. Calculations relying on the old precision need an explicit override:
+
+```ts
+const hf = HyperFormula.buildEmpty({
+  licenseKey: 'gpl-v3',
+  precisionRounding: 14,  // pre-v3 behavior
+});
+```

.agents/skills/hyperformula/references/custom-functions.md

@@ -0,0 +1,174 @@
+# Custom Functions
+
+Extend HyperFormula with your own functions via `FunctionPlugin`. Authoritative doc:
+- Custom functions guide: https://hyperformula.handsontable.com/docs/guide/custom-functions.html
+
+## Minimal plugin
+
+Register **before** creating any instance — functions registered after `buildFromArray` / `buildFromSheets` / `buildEmpty` won't be available.
+
+```ts
+import { HyperFormula, FunctionPlugin, FunctionArgumentType } from 'hyperformula';
+
+class MyPlugin extends FunctionPlugin {
+  greet(ast, state) {
+    return this.runFunction(
+      ast.args,
+      state,
+      this.metadata('GREET'),
+      (name) => `Hello, ${name}!`
+    );
+  }
+}
+
+MyPlugin.implementedFunctions = {
+  GREET: {
+    method: 'greet',
+    parameters: [{ argumentType: FunctionArgumentType.STRING }],
+  },
+};
+
+const translations = { enGB: { GREET: 'GREET' }, enUS: { GREET: 'GREET' } };
+
+// PITFALL: registration MUST happen before any instance is built.
+HyperFormula.registerFunctionPlugin(MyPlugin, translations);
+
+const hf = HyperFormula.buildFromArray(
+  [['World', '=GREET(A1)']],
+  { licenseKey: 'gpl-v3' }
+);
+console.log(hf.getCellValue({ sheet: 0, col: 1, row: 0 })); // "Hello, World!"
+```
+
+## Volatile functions
+
+Mark a function as volatile so it recalculates on every change (like `RAND` or `NOW`). Volatile functions are expensive in large sheets — use sparingly.
+
+```ts
+MyPlugin.implementedFunctions = {
+  RAND_ID: {
+    method: 'randId',
+    parameters: [],
+    isVolatile: true,
+  },
+};
+```
+
+## Argument types
+
+```ts
+import { FunctionArgumentType } from 'hyperformula';
+
+// FunctionArgumentType.NUMBER
+// FunctionArgumentType.STRING
+// FunctionArgumentType.BOOLEAN
+// FunctionArgumentType.NOERROR
+// FunctionArgumentType.SCALAR
+// FunctionArgumentType.RANGE       // accepts a cell range
+// FunctionArgumentType.ANY
+```
+
+Use `optionalArg: true`, `defaultValue`, and `minValue` / `maxValue` to validate arguments declaratively:
+
+```ts
+MyPlugin.implementedFunctions = {
+  CLAMP: {
+    method: 'clamp',
+    parameters: [
+      { argumentType: FunctionArgumentType.NUMBER },
+      { argumentType: FunctionArgumentType.NUMBER, optionalArg: true, defaultValue: 0 },
+      { argumentType: FunctionArgumentType.NUMBER, optionalArg: true, defaultValue: 100 },
+    ],
+  },
+};
+```
+
+## Range arguments
+
+Use `RANGE` argument type when the function takes a cell area. The callback receives the range as a 2D array.
+
+```ts
+class SumPositivesPlugin extends FunctionPlugin {
+  sumPositives(ast, state) {
+    return this.runFunction(
+      ast.args,
+      state,
+      this.metadata('SUM_POSITIVES'),
+      (range) => {
+        let total = 0;
+        for (const row of range.data) {
+          for (const v of row) if (typeof v === 'number' && v > 0) total += v;
+        }
+        return total;
+      }
+    );
+  }
+}
+
+SumPositivesPlugin.implementedFunctions = {
+  SUM_POSITIVES: {
+    method: 'sumPositives',
+    parameters: [{ argumentType: FunctionArgumentType.RANGE }],
+  },
+};
+```
+
+## Returning arrays
+
+Custom functions can return 2D arrays. **PITFALL:** result arrays don't auto-resize when upstream dependencies change — the footprint is fixed at first evaluation.
+
+```ts
+class SplitPlugin extends FunctionPlugin {
+  splitToRow(ast, state) {
+    return this.runFunction(
+      ast.args,
+      state,
+      this.metadata('SPLIT_ROW'),
+      (text, sep) => [text.split(sep)]  // 2D array: one row, N cols
+    );
+  }
+}
+```
+
+## Error handling
+
+Return a `CellError` to signal a formula error:
+
+```ts
+import { CellError, ErrorType } from 'hyperformula';
+
+class DividePlugin extends FunctionPlugin {
+  safeDivide(ast, state) {
+    return this.runFunction(
+      ast.args,
+      state,
+      this.metadata('SAFE_DIVIDE'),
+      (a, b) => (b === 0 ? new CellError(ErrorType.DIV_BY_ZERO) : a / b)
+    );
+  }
+}
+```
+
+## Aliases and localized names
+
+Expose one method under multiple function names, or localize:
+
+```ts
+MyPlugin.aliases = {
+  HELLO: 'GREET', // calling =HELLO(x) runs the greet() method
+};
+
+const translations = {
+  enGB: { GREET: 'GREET' },
+  plPL: { GREET: 'POWITAJ' }, // =POWITAJ("Świat") in Polish
+};
+HyperFormula.registerFunctionPlugin(MyPlugin, translations);
+```
+
+## Unregister / introspect
+
+```ts
+HyperFormula.unregisterFunctionPlugin(MyPlugin);
+HyperFormula.unregisterFunction('GREET');
+HyperFormula.getRegisteredFunctionNames('enGB');
+```

.agents/skills/hyperformula/references/error-handling.md

@@ -0,0 +1,69 @@
+# Error Handling
+
+Inspect cell values that may be errors, tell error types apart, and check value shape. Authoritative docs:
+- Types of errors: https://hyperformula.handsontable.com/docs/guide/types-of-errors.html
+- Types of values: https://hyperformula.handsontable.com/docs/guide/types-of-values.html
+
+## Always check `CellError` before using a result
+
+Cell values can be errors (`#DIV/0!`, `#VALUE!`, `#REF!`, etc.). Always test before using a result.
+
+```ts
+import { CellError, ErrorType } from 'hyperformula';
+
+const value = hf.getCellValue({ sheet: 0, col: 0, row: 0 });
+
+if (value instanceof CellError) {
+  // ErrorType enum: DIV_BY_ZERO, VALUE, REF, NAME, NUM, NA, CYCLE, ERROR
+  switch (value.type) {
+    case ErrorType.CYCLE:
+      console.log('Circular reference');
+      break;
+    case ErrorType.NAME:
+      // Usually: function not registered (check plugin registration or i18n language)
+      console.log('Unknown name:', value.message);
+      break;
+    default:
+      console.log('Error:', value.type, value.message);
+  }
+} else {
+  console.log('Value:', value);
+}
+```
+
+## `#CYCLE!` is HyperFormula-specific
+
+Standard spreadsheet apps report cycles differently. HyperFormula's `IF` also reports cycles for all branches, even unreachable ones — this can produce `#CYCLE!` in formulas that Excel or Sheets would evaluate.
+
+## Inspect value shape without catching errors
+
+```ts
+import { CellValueDetailedType } from 'hyperformula';
+
+hf.getCellValueDetailedType({ sheet: 0, col: 0, row: 0 });
+// → CellValueDetailedType.NUMBER | STRING | BOOLEAN | ERROR | EMPTY | ...
+```
+
+Use the detailed type when you need to distinguish e.g. number vs empty without touching the value.
+
+## Returning errors from custom functions
+
+Custom `FunctionPlugin` methods can return a `CellError` to surface a formula error. See [custom-functions.md](custom-functions.md) for the full pattern.
+
+```ts
+import { CellError, ErrorType } from 'hyperformula';
+
+return new CellError(ErrorType.DIV_BY_ZERO);
+```
+
+## Common causes
+
+| Error | Common cause |
+|---|---|
+| `#NAME?` | Function not registered (check `registerFunctionPlugin` order or `language` config) |
+| `#CYCLE!` | Circular reference — or an `IF` branch that *could* produce one |
+| `#REF!` | Deleted row/column broke a formula reference |
+| `#VALUE!` | Type mismatch — e.g. passing a string where a number is expected |
+| `#DIV/0!` | Division by zero, including empty cells coerced to 0 |
+| `#NUM!` | Out-of-range numeric result (e.g. `SQRT(-1)`) |
+| `#N/A` | Lookup miss (`MATCH`, `VLOOKUP`) or propagated from an upstream `#N/A` |