@baravak/risloo-profile-cli 4.46.2 → 4.70.0

package/.agents/skills/create-profile/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: create-profile
+description: Build a new psychological profile (نیم‌رخ) or a new page/chart of one — or edit an existing profile's chart — from a Figma design into a JS controller (src/samples/<NAME>.js) + Handlebars SVG template (views/profiles/samples/<NAME>*.hbs). Use when the user wants to create/extend/edit a profile, references Figma SVG/HTML exports (x/<NAME>.svg, x/<NAME>.html) for a <NAME>, or asks to wire a `score` dataset into a chart. Read AGENTS.md alongside this skill — it holds the conventions, helper reference, and the Gotchas this skill points to.
+---
+
+# create-profile (pointer)
+
+This is a shortcut. The full runbook lives in one place, shared by every agent:
+
+**`.claude/skills/create-profile/SKILL.md`**
+
+Read that file end to end **now**, before taking any task action, then follow it. Also read `AGENTS.md` at the repo root — the runbook references its _Handlebars Helper Reference_, _Gotchas & Reusable Patterns_, and conventions instead of repeating them.
+
+Do not edit this pointer to add content; edit the runbook above.

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)"
+    ]
+  }
+}

package/.claude/skills/create-profile/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: create-profile
+description: Build a new psychological profile (نیم‌رخ) or a new page/chart of one — or edit an existing profile's chart — from a Figma design into a JS controller (src/samples/<NAME>.js) + Handlebars SVG template (views/profiles/samples/<NAME>*.hbs). Use when the user wants to create/extend/edit a profile, references Figma SVG/HTML exports (x/<NAME>.svg, x/<NAME>.html) for a <NAME>, or asks to wire a `score` dataset into a chart. Read AGENTS.md alongside this skill — it holds the conventions, helper reference, and the Gotchas this skill points to.
+---
+
+# Create / edit a profile (نیم‌رخ)
+
+This project renders psychological-test results into SVG/PNG profiles. A profile = a JS controller (`src/samples/<NAME>.js`) + one or more Handlebars templates (`views/profiles/samples/<NAME>.hbs`, or `<NAME>_1.hbs`, `<NAME>_2.hbs`, … for multi-page). Follow this runbook. **Read `AGENTS.md` first** — this skill references its _Handlebars Helper Reference_, _Gotchas & Reusable Patterns_, and conventions instead of repeating them.
+
+## Core principle — you produce the RAW chart only
+
+You draw only the Figma **Chart** layer (the raw chart). The engine injects the header, sidebar and footer via the `{{#> layout}}` wrapper. **Never put header/sidebar/footer in the HBS.** The CLI emits a `raw` variant (chart only) and a full with-sidebar variant. (AGENTS.md › _What the HBS Draws_.)
+
+## 1. Gather inputs — ask the user for these 6 files (as prompts)
+
+1. **Scoring source** — the engine that computes the `score` object. Its **language varies (PHP, Python, or Node.js)** and it usually lives in a sibling repo (e.g. for NEO: `../risloo-docker/services/risloo/app/Score<NAME>.php` + trait). Don't assume the language/path — ask. It tells you how each `score` key is computed and what flags mean.
+2. **Scoring documentation** — the validity rules, thresholds, and level/norm descriptions (a file or pasted text).
+3. **Profile SVG** — `x/<NAME>.svg`. The **source of truth**: which elements exist, exact coordinates, and styling (e.g. a line that looks solid in HTML is `stroke-dasharray` dashed here).
+4. **Profile HTML** — `x/<NAME>.html`. A **helper** only: SVG text is outlined paths, so use the HTML to read the text content and learn **where each label goes (and where it doesn't)**, plus colors/gradients. If the HTML has an element the SVG lacks, it's a disabled Figma layer — drop it (AGENTS.md › Gotchas).
+5. **Profile JSON** — `src/publish/json/profiles/<NAME>.json` (input dataset; its `score` object drives everything).
+6. **Reference PNG** — the designer's rendered export of the **Chart** layer (same variant as the CLI `raw` output, *not* the full sidebar page). This is the validation target for step 7: at the end you render your own `raw` PNG and visually match it against this one. Note which demo data it was rendered with (usually the values in the HTML) so the JSON reproduces the same bar positions.
+
+Then **ask for the designer's Figma comments** — thresholds, coefficients, the inside/outside text threshold, validity logic. The Figma MCP / SVG / HTML do **not** contain comments, and these specs usually live only there. Don't start coding until you have them.
+
+If the SVG and HTML disagree (an element present in one, absent in the other, or a different layout), surface it and ask which is authoritative before building.
+
+## 2. Pick a base profile
+
+Find the closest existing profile and copy its idioms rather than writing from scratch:
+- Horizontal bars + validity boxes → `src/samples/FRHPT93.js` + `views/profiles/samples/FRHPT93_2.hbs`.
+- A simple 5-row bar chart → `src/samples/BSCT93.js`.
+- The most recent full example built with this skill → `src/samples/NEO93.js` + `views/profiles/samples/NEO93_1.hbs`.
+
+Read its JS + HBS end to end.
+
+## 3. Geometry (from the SVG)
+
+- The Figma **Chart** layer = the SVG `viewBox` (e.g. `0 0 800 674`).
+- `dimensions = Chart + 2·padding`; derive `padding` from `(Main − Chart)/2` using the HTML offset (e.g. content at `left:72 top:40` inside a `943×754` frame → `{x:71.5, y:40}`).
+- Draw all content inside `<g transform="translate(padding.x, padding.y)">`.
+- **Transcribe verbatim**, in the SVG's element order, the static parts: gridlines (`line`), tracks/boxes (`rect`), `linearGradient`, `filter`, icon `path`s. Draw order = z-order — keep it (e.g. a shadowed baseline drawn *after* the bars sits in front).
+- **Reconstruct** every text run as a real `<text>` at the SVG's x/y — Figma exports text as outlined `<path>`, never `<text>` (AGENTS.md › Gotchas).
+- Check the **axis**: if gridline positions look "irregular", they may be a zoomed range. Derive the linear map `x = a·pct + b` from two `(label, x)` pairs and draw the bars on that scale (AGENTS.md › Gotchas › Custom/zoomed axis).
+- **Alignment is the whole job.** This is pixel-precise infographic work — measure exact x/y (and text glyph bounds) from the SVG; never estimate. Get every label's horizontal alignment (left/center/right via `text-anchor`, RTL-aware) and vertical alignment (row mid-line, shared baseline) right. If the chart sits in an offset frame, transcribe its `translate` exactly. See AGENTS.md › Gotchas › _Alignment is the whole job_.
+
+## 4. Wire the data
+
+- In the controller, define `labels` so each entry's `eng` matches a `score` key; `Object.values(this.labels)` feeds `Dataset._extractData`, producing `dataset.score = [{ label, mark }]`.
+- In `_calcContext()`, read **every** mark with `?? 0` (AGENTS.md › `?? 0` rule) — `_extractData` turns a `0` into `undefined`. Compute per-item geometry (bar width / percentage, text x + anchor) and any validity indicators.
+- Confirm ambiguous encodings (validity flags `1`=valid vs invalid, reversed answer scales, norm-based levels) against the **scoring source** (PHP/Python/Node.js) — never guess.
+
+## 5. Write the controller + template
+
+- **Controller**: `labels`; `profileSpec` (`sample`, `profile.dimensions`/`padding`, `labels: Object.values(this.labels)`); `constructor` calling `this._init(...)`; `_calcContext()` returning one context object per page.
+- **Template**: `{{#> layout}}` → `<defs>` (gradients/clips/filters) → `<g transform="translate(padding.x, padding.y)">` → static structure + `{{#each items}}` rows + conditional boxes → `{{/layout}}`.
+- Use the helpers from AGENTS.md › _Helper Reference_ (`bar`, `math`, `boolean`, `ternary`, `object`, `toRad`). Apply the gotcha checklist below.
+
+## 6. Multi-page
+
+- Set `static pages = N`; build `<NAME>_1.hbs … <NAME>_N.hbs`. Create blank `{{#> layout}} … {{/layout}}` placeholders for pages not built yet — **a missing template file errors the whole run**.
+- Make `profile.dimensions` / `profile.padding` arrays (indexed `page-1` by `layout.hbs`); give each page a `titleAppend`.
+
+## 7. Verify
+
+- Render: `./bin/risloo.js E <NAME> -d ./src/publish/json/profiles/<NAME>.json -a ./temp`
+- Open `temp/<NAME>.raw.png` (chart only) and `temp/<NAME>.png` (with sidebar); eyeball against `x/<NAME>.svg` / `x/<NAME>.html`.
+- Test edge & validity states with **scratch JSONs** that modify the `score` object (flip a `voption_*`/validity flag, push a value to 0% or 100%) and render with `-d <scratch>.json`. Clean up scratch files afterward.
+- **Close with a PNG visual match (the final gate).** Render with the **same data the reference PNG used** (the demo values from the HTML) so bars land in the same place, then **view both** `temp/<NAME>.raw.png` and the reference PNG (Read them) and compare region by region. Your eyes catch structural/color/placement/RTL errors but are **not a pixel ruler** — when your eye flags a spot, pull the exact coordinate from the **SVG** and fix from that number, then re-render. Iterate render → view → fix until the two match. (AGENTS.md › Gotchas › _Close with a PNG visual match_.)
+
+## Gotcha checklist (detail in AGENTS.md › Gotchas)
+
+- [ ] RTL `text-anchor`: right-align Persian with `start`; inside-bar `%` `start`, outside `end`.
+- [ ] `?? 0` on every mark read in `_calcContext`.
+- [ ] Text reconstructed as `<text>`, not transcribed glyph paths.
+- [ ] Western digits in templates (the `DanaFaNum` font shapes them to Persian).
+- [ ] Elements emitted in Figma-SVG order (draw order = z-order).
+- [ ] Bars drawn on the same scale as the (possibly zoomed) axis labels.
+- [ ] Validity/alert boxes hidden unless ≥1 indicator; separator dots via `{{#unless last}}`.
+- [ ] No header/sidebar/footer in the HBS — only the Chart layer.
+- [ ] Closed with a PNG visual match against the reference (raw-vs-raw, same data): viewed both images, iterated render → view → fix until aligned.

package/AGENTS.md

@@ -0,0 +1,239 @@
+# AGENTS.md
+
+> Single source of truth for agent instructions in this repo (Codex, Claude Code, …).
+> `CLAUDE.md` is only a pointer to this file — edit **this** file, never the pointer.
+
+## Skills (runbooks)
+
+| Skill | Path | Use for |
+|---|---|---|
+| `create-profile` | `.claude/skills/create-profile/SKILL.md` | Create / extend / edit a profile (نیم‌رخ) from a Figma design → JS controller + HBS template. `.agents/skills/create-profile/SKILL.md` is a vendor-neutral pointer to the same file (Codex scans `.agents/skills` from the cwd up to the repo root). |
+
+## Project Overview
+
+**@baravak/risloo-profile-cli** is a Node.js CLI tool that converts psychological test result JSON data into SVG and PNG profile/report images. It supports 81+ psychological questionnaires with Persian/Farsi labeling.
+
+Published as npm package: `@baravak/risloo-profile-cli` (v4.46.2, MIT)
+
+---
+
+## Directory Structure
+
+```
+risloo-extractor-app/
+├── bin/
+│   └── risloo.js                # CLI entry point
+├── src/
+│   ├── cli.js                   # Commander.js command definitions
+│   ├── cli-commands/
+│   │   ├── Executor.js          # Base executor class
+│   │   ├── ExtractExecutor.js   # Profile/report/sheet extraction logic
+│   │   ├── GiftExecutor.js      # Gift card generation
+│   │   └── utilities/           # BaseOps, Benchmarker, Response, Errors, Status codes
+│   ├── Profile.js               # Base Profile class (math utilities)
+│   ├── Gift.js                  # Gift card class
+│   ├── samples/                 # JS controller files — one per profile (e.g. BSCT93.js)
+│   ├── handlebars/
+│   │   ├── init.js              # Handlebars initialization
+│   │   ├── helpers.js           # Entry point for all helpers
+│   │   ├── helpers/             # 45+ geometry helper modules
+│   │   ├── importPartials.js    # Partials loader
+│   │   └── polygon.js           # Polygon drawing logic
+│   ├── helpers/                 # Math helpers (angleABS, polarXY, gauge, polygonXY)
+│   ├── qrcode/                  # QR code generation & rendering
+│   └── publish/
+│       ├── json/profiles/       # Template JSON per sample (e.g. BSCT93.json)
+│       ├── json/gift/           # Gift template data
+│       ├── test.js              # Auto-test all samples
+│       └── bot.js               # Post-publish automation
+├── views/
+│   ├── profiles/samples/        # Handlebars SVG templates (.hbs)
+│   └── gift.hbs
+└── package.json
+```
+
+---
+
+## Commands
+
+```bash
+# Test a single profile (generates SVG in ./temp)
+./bin/risloo.js E <NAME> -d ./src/publish/json/profiles/<NAME>.json -a ./temp
+
+# Watch mode
+risloo extract <NAME> profile -i local -d ./src/publish/json/profiles/<NAME>.json -o local -a ./temp -w
+
+# Generate gift card
+risloo gift -i raw-json -d '{"code":"..."}' -o local -a ./output
+
+# Test all samples
+npm test   # → node ./src/publish/test.js
+```
+
+---
+
+## Profile Development Workflow (Figma → Code)
+
+### Design Source
+
+Each profile is designed in Figma. Per task, one or both of the following may be provided:
+
+- **Figma design file** — connect via Figma MCP to read layer dimensions and structure. The relevant layer is named **Chart**.
+- **Figma handoff file** — contains additional implementation notes and specs. May state that this profile is similar to an existing one (e.g. "similar to BSCT93 with these changes"). In that case: find the referenced profile's JS + HBS files, use them as the base, and apply only the described differences.
+
+> **Important:** The Figma MCP reads text layers only — it does NOT read Figma comments. Designers often leave critical specs (thresholds, coefficients, pixel values) as Figma comments. Always ask the user to share designer comments before finalizing the plan.
+
+### What the HBS Draws
+
+The HBS file draws **only the Chart layer** — i.e. the **raw** chart. The engine produces the final page by automatically injecting the header (test name, dates, client info), the sidebar (logo, room info, prerequisites) and the footer/closing info via the `{{#> layout}}` wrapper. Never include any of these in the HBS. (The CLI emits both a `raw` variant — chart only, e.g. `<NAME>.raw.svg/png` — and the full with-sidebar variant `<NAME>.svg/png`.)
+
+### SVG Coordinate System
+
+Since this is SVG, coordinate origin matters for correctness across **all** inputs:
+
+- **x=0** = left edge, increases rightward
+- **y=0** = top edge, increases downward
+- Horizontal bars fill left → right: `{{bar (BAR_WIDTH * factor.p) height ...}}`
+- Vertical total bar fills bottom → up via the transform trick: `translate(0, barHeight - barHeight * p)`
+- All positions must remain stable for edge-case inputs: 0% score, 100% score, missing data
+
+### Inside/Outside Bar Text
+
+When rendering percentage text on a bar, check if the bar is wide enough to contain the text. The threshold is specified by the designer per profile (in Figma comments):
+
+```hbs
+{{#if (boolean factor.percentage '<=' THRESHOLD)}}
+  <text x="{{math (math BAR_WIDTH '*' factor.p) '+' 6}}" ...>{{factor.percentage}} ٪</text>
+{{else}}
+  <text x="{{math (math BAR_WIDTH '*' factor.p) '-' 4}}" ...>{{factor.percentage}} ٪</text>
+{{/if}}
+```
+
+### File Structure per Profile
+
+Each profile (نیم‌رخ) consists of three files:
+
+| File | Path | Role |
+|---|---|---|
+| JSON template | `src/publish/json/profiles/<NAME>.json` | Test data / input template |
+| JS controller | `src/samples/<NAME>.js` | Data processing, geometry config |
+| HBS template | `views/profiles/samples/<NAME>.hbs` | SVG rendering |
+
+If a profile has **multiple pages**, the HBS files are named with suffixes:
+- `<NAME>_1.hbs`, `<NAME>_2.hbs`, `<NAME>_3.hbs`, ...
+
+Multi-page mechanics:
+- Set `static pages = N` on the controller class. `ExtractExecutor.js` then loads `<NAME>_1.hbs … <NAME>_N.hbs` (a single-page profile uses the un-suffixed `<NAME>.hbs`). **A missing template file errors the whole run** — when a page isn't built yet, create a blank `{{#> layout}} … {{/layout}}` placeholder for it.
+- `profile.dimensions` and `profile.padding` become **arrays**; `layout.hbs` picks index `page - 1` for each page. Each entry returned by `_calcContext()` is one page's context object and may carry a `titleAppend` string that is appended to the header title.
+
+### Dimensions & Padding Convention
+
+The chart drawing must fit within the **Main** layer in Figma.
+
+- Read the **Main** layer dimensions from Figma
+- `profile.padding` = 20 units per side
+- The `x` and `y` values (drawing area) = Main dimensions minus one padding unit each:
+  - e.g. Main = 104×255 → `{ x: 84, y: 235 }`
+
+The `dimensions` property in the JS controller adds padding back on both sides of the **Chart** layer dimensions:
+
+```js
+get dimensions() {
+  return {
+    width: 736 + 2 * this.padding.x,   // Chart layer width from Figma
+    height: 254 + 2 * this.padding.y,  // Chart layer height from Figma
+  };
+},
+```
+
+### Data / Labels Convention
+
+All data needed for rendering goes in the `labels` property of the JS controller.
+
+The data structure is typically derived from a Python script that outputs a JSON file — flattened with `_` separators — which maps source fields to their `labels` keys.
+
+```js
+get labels() {
+  return {
+    // flat_key: value
+    score_total: ...,
+    subscale_anxiety: ...,
+  };
+}
+```
+
+**Where the `score` values come from.** The JSON `score` object fed to a profile is produced by a separate **scoring engine** whose language **varies per test — it may be PHP, Python, or Node.js** — and which usually lives in a sibling repo (e.g. for NEO: `../risloo-docker/services/risloo/app/ScoreNEO93.php` plus a shared `ScoreNEO` trait). **Always ask the user for the actual scoring-source file** rather than assuming the language/path. When a score key's meaning is ambiguous — especially validity flags (is `1` valid or invalid?) — read that source to confirm the encoding instead of guessing; the scoring source also defines the level thresholds (norms) and per-item (reverse) scoring. Each `score` key is matched to a label via `label.eng`.
+
+**The `?? 0` rule.** `Dataset._extractData` (in `src/Profile.js`) maps `mark: score[label.eng] || …`, so a score of `0` (or any falsy value) falls through to `undefined`. Always read marks with `?? 0` in `_calcContext` to avoid `NaN` widths/positions.
+
+---
+
+## Handlebars Helper Reference
+
+Common helpers used in profile templates (defined under `src/handlebars/helpers/`):
+
+| Helper | Signature | Notes |
+|---|---|---|
+| `bar` | `bar W H (object tl= bl= tr= br=) (toRad deg) ...attrs` | Rounded-rect `<path>` — the building block for every fill bar. For a horizontal bar use `tl=bl=0` and round `tr/br`. The hash accepts `fill`, `fill-opacity`, `stroke`, `clip-path`, `transform`. |
+| `math` | `math a op b` | Arithmetic `+ - * / %` (op defaults to `+`). Nestable: `(math (math …) '*' …)`. |
+| `boolean` | `boolean a op b` | Comparison/logical `=== !== == != < <= > >= && \|\|`. |
+| `ternary` | `ternary cond a b` | Returns `a` if `cond` is truthy, else `b`. |
+| `object` | `object k=v …` | Builds an inline object literal (used for the `bar` corner radii). |
+| `toRad` | `toRad deg` | Degrees → radians. |
+
+---
+
+## Gotchas & Reusable Patterns
+
+Hard-won knowledge that applies to **every** profile:
+
+- **Alignment is the whole job — measure, never estimate.** These are pixel-precise **infographics** built from SVG, so every element must line up with the design **both horizontally and vertically**. Pull exact coordinates from the SVG (element `x`/`y`; for text-as-paths, the glyph bounding box / the `M…` start) instead of eyeballing. **Horizontal:** decide per label whether it is left-, center-, or right-aligned and set `text-anchor` to match (RTL flips `start`/`end`) — e.g. the right-most axis label's *right edge* sits on the gridline (right-aligned), not centered over it; domain names are right-aligned to a fixed edge with the dash/letter at fixed x's after them. **Vertical:** center row text on the row mid-line with `y=<center> dy=".3em"`, and keep every column of a row on the same baseline. If the chart lives inside an offset frame (NEO93 page 1 = `translate(32, 128)` inside the 800×674 content), transcribe that `translate` exactly, and remember a `filterUnits="userSpaceOnUse"` region is in that same (post-translate) local space. Re-render and eyeball after **every** change.
+- **RTL is the base — account for it in EVERY alignment.** The root SVG sets `direction="rtl"` (`views/profiles/layout.hbs`), which flips both horizontal text flow **and** the advance direction of rotated labels. This is the single most common alignment mistake — get it wrong and a label slides *under* a bar or lands a whole run-length away. Two cases:
+    - **Horizontal `text-anchor`.** Under RTL, `text-anchor="start"` puts the **right** edge at `x` (text grows **left**); `text-anchor="end"` puts the **left** edge at `x` (text grows **right**). So: right-align Persian labels with `start`; a label that must sit to the **right** of an element and grow away from it uses `end`. Inside-bar `%` label → `start`; outside (narrow-bar) label → `end` (mirror `FRHPT93_2.hbs`). BSCT93 vertical total bar: the `%`/ratio labels sit to the **right** of the bar → `end`; the `٪۱۰۰` axis label sits to the **left** → `start` (using `end` there grows it rightward *under* the bar, which is drawn after and paints over it). If a run of Latin/numbers mis-orders, add `direction="ltr"` on that `<text>`.
+    - **Rotated (`rotate(-90)`) vertical labels advance DOWN, not up.** Because the base is RTL, a `<text transform="rotate(-90,0,0) translate(tx,ty)">` grows **downward** on screen (its reading run goes top→bottom). So the baseline x = `<group-x> + ty` (glyph bodies extend **left** of it) and the text's **TOP** edge = `<group-y> − tx`, running down for its length. BSCT93 «نمره کل» under group `translate(637,1)` → `ty=22` (baseline x≈659), `tx=-202` (top y≈203, bottom ≈238). Assuming it grows *up* drops it ~a run-length too low.
+- **`?? 0` on every mark.** See _Data / Labels Convention_ — `_extractData` turns a `0` mark into `undefined`; always guard with `?? 0`.
+- **Figma SVG = outlined paths, not text.** A Figma SVG export renders every text run as an outlined `<path>`, never `<text>`. Do **not** transcribe glyph paths. Reconstruct text with real `<text>` elements at the SVG's x/y, and take the actual content/colors from the **HTML** export. Transcribe verbatim only: `rect`, `line`, `linearGradient`, `filter`, and icon `<path>`s.
+- **The SVG is the source of truth; the HTML export is only a helper.** Trust the **SVG** for everything authoritative: which elements exist, exact coordinates, and styling — e.g. a divider that looks like a plain solid line in the HTML is actually `stroke-dasharray` *dashed* in the SVG. Use the **HTML** only because (a) SVG text is outlined paths so you can't read it there — the HTML tells you the text content and **where each label goes (and where it doesn't)**, and (b) it's easier to read colors/gradients/structure. If the HTML shows an element the SVG lacks, it's a *disabled Figma layer* (the HTML export still draws disabled layers, with color) — **drop it**. (NEO93 level chips were exactly this: present in HTML, absent in SVG → removed; the level *text* stays, the chip box doesn't.)
+- **Persian digits come from the font.** Emit Western digits in templates (`{{item.mark}}`, `از 192`, `50 ٪`); the `DanaFaNum` font shapes them to Persian. Never hand-convert.
+- **Draw order = z-order.** Later elements paint on top. Transcribe in the same order as the Figma SVG (e.g. a shadowed baseline drawn **after** the bars sits in front of them).
+- **Custom / zoomed axis.** Gridlines are not always 0–100%. If their positions look "irregular", check for a zoomed range (e.g. NEO93 = 20–80%). Derive the linear map `x = a·pct + b` from two known `(label, x)` pairs and draw the bars on **that** scale, so a bar's end lands exactly on its labeled gridline.
+- **Validity / alert-box pattern.** Lay indicators right-to-left: text at `x = ANCHOR − (start + length/2)`, separator dot at `ANCHOR − (start + length + 26)` guarded by `{{#unless last}}`; hide the whole box unless ≥1 indicator is active. Drive it from JS with per-item `{ start, length, last }` (see `FRHPT93.js` / `NEO93.js`).
+- **Close with a PNG visual match — your eye finds *where*, the SVG gives *what*.** The final gate before delivery: render the `raw` PNG and, by actually **viewing both images** (Read the two PNGs), compare it against the designer's reference PNG. Match variants — the reference must be a **Chart-layer** export (same as the CLI `raw`), never the full sidebar page. Render with the **same data the reference used** (transcribe the demo values from the HTML into the JSON), or bars land at different positions and every difference is a false alarm. Your vision reliably catches **structural** errors — wrong gradient/color, a label flipped to the wrong side (RTL), a bar whose end misses its gridline, reordered rows, a dropped or extra element — but it is **not a pixel ruler**: never trust it for 1–3px nudges. So when your eye flags a spot, go back to the **SVG**, read the exact coordinate, and fix from that number (eye = *where*, SVG = *what*). Iterate render → view → fix until the two PNGs match; that match is the close of the job. (This complements — never replaces — HTML-vs-output text checking, since outlined/rendered text is too noisy for a visual diff to judge.)
+
+---
+
+## Tech Stack
+
+| Area | Technology |
+|---|---|
+| Language | JavaScript (Node.js, no build step) |
+| CLI | Commander.js |
+| Templating | Handlebars (SVG generation) |
+| Image output | Sharp (SVG → PNG) |
+| Dates | Moment.js + moment-jalaali (Persian calendar) |
+| QR codes | qrcode |
+| File watching | Chokidar |
+| Package manager | Yarn |
+| Design source | Figma (via MCP) |
+
+---
+
+## Naming Conventions
+
+- `items` — array of data elements to draw
+- `raw` — total/aggregate element
+- `ticks` — graduation marks on profiles
+- `s` suffix — denotes arrays (not `Arr`)
+- Sample names: uppercase acronym + year (e.g. `BSCT93`, `BEQI93`, `16PF93`)
+- Dataset score structure: `dataset.score = [{ label: { eng, ... }, mark }]`
+
+---
+
+## Publishing
+
+```bash
+npm version <patch|minor|major>
+npm publish
+# prepublishOnly: npm test
+# postpublish: npm run bot
+```

package/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+Pointer only — all project instructions live in [AGENTS.md](AGENTS.md). Edit that file, not this one.
+
+@AGENTS.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baravak/risloo-profile-cli",
-  "version": "4.46.2",
+  "version": "4.70.0",
   "description": "**Risloo Profile CLI** is a library for creating profiles, reports and sheets for *psychological* samples.",
   "main": "bin/risloo.js",
   "publishConfig": {

package/src/cli-commands/Executor.js

@@ -1,5 +1,5 @@
 const { checkAndLoad, loadStdin, ensureDirExistence, createSVG, createPNG } = require("./utilities/BaseOps");
-const Handlebars = require("../handlebars/init");
+const createHandlebars = require("../handlebars/init");
 const path = require("path");
 const Benchmarker = require("./utilities/Benchmarker");
 const Response = require("./utilities/Response");
@@ -74,8 +74,14 @@ class Executor {
     }
   }
 
+  _addHandlebarsPromise(partials = {}) {
+    this.promises["handlebars"] = Promise.resolve(partials).then(createHandlebars);
+    return this.promises["handlebars"];
+  }
+
   async _renderTemplate(ctx, templateBuffer) {
-    const template = (await Handlebars).compile(templateBuffer.toString(), "utf-8");
+    const hbs = await this.promises.handlebars;
+    const template = hbs.compile(templateBuffer.toString(), "utf-8");
     return template(ctx);
   }
 

package/src/cli-commands/ExtractExecutor.js

@@ -7,7 +7,8 @@ const { FileNotFoundError } = require("./utilities/CustomErrors");
 
 class ExtractExecutor extends Executor {
   samplesJSDir = path.join(__dirname, "..", "samples");
-  profilesTemplatesDir = path.join(__dirname, "..", "..", "views", "profiles", "samples");
+  profilesDir = path.join(__dirname, "..", "..", "views", "profiles");
+  profilesTemplatesDir = path.join(this.profilesDir, "samples");
 
   constructor(options) {
     super(options);
@@ -39,6 +40,18 @@ class ExtractExecutor extends Executor {
     });
   }
 
+  _addProfileHandlebarsPromise() {
+    const { promises, response } = this;
+    const partials = promises["js"].then((Profile) => Profile.partials || {});
+    const handlebarsPromise = this._addHandlebarsPromise(partials);
+
+    promises["handlebars"] = handlebarsPromise.catch((err) =>
+      response.setStatus(EXTRACT_STATUS["TEMPLATE_NOT_FOUND"], err)
+    );
+
+    return promises["handlebars"];
+  }
+
   _addProfilesTemplatePromises() {
     const { sample, dirs, profilesTemplatesDir, promises, response } = this;
 
@@ -77,6 +90,7 @@ class ExtractExecutor extends Executor {
         name: options.name,
       };
 
+      this._addProfileHandlebarsPromise();
       this._addProfilesTemplatePromises();
     }
 
@@ -124,7 +138,7 @@ class ExtractExecutor extends Executor {
   }
 
   _watch() {
-    const { command, dirs, input, response, benchmarker, promises } = this;
+    const { dirs, input, promises } = this;
 
     const opts = {
       awaitWriteFinish: {
@@ -137,38 +151,58 @@ class ExtractExecutor extends Executor {
       dirs.templates.map((templateFileDir, index) => {
         chokidar.watch(templateFileDir, opts).on("change", () => {
           promises["templates"][index] = checkAndLoad(templateFileDir);
-          benchmarker?.restart(command);
-          this._createProfile("with-sidebar", ["svg"]).then(() => {
-            benchmarker?.end();
-            response.setTime(benchmarker?.totalTime);
-            response.showOutput();
-          });
+          this._renderWatchedProfile();
         });
       });
     });
 
+    this._resetPartialWatcher(opts).catch(() => {});
+
     chokidar.watch(dirs.sampleJS, opts).on("change", () => {
       promises["js"] = checkAndImport(dirs.sampleJS);
-      benchmarker?.restart(command);
-      this._createProfile("with-sidebar", ["svg"]).then(() => {
-        benchmarker?.end();
-        response.setTime(benchmarker?.totalTime);
-        response.showOutput();
-      });
+      this._addProfileHandlebarsPromise();
+      this._resetPartialWatcher(opts).catch(() => {});
+      this._renderWatchedProfile();
     });
     
     if(input.type === 'local') chokidar.watch(input.data, opts).on('change', () => {
       promises["input"] = checkAndLoad(input.data).then((json) => Promise.resolve(JSON.parse(json)));
-      benchmarker?.restart(command);
-      this._createProfile("with-sidebar", ["svg"]).then(() => {
-        benchmarker?.end();
-        response.setTime(benchmarker?.totalTime);
-        response.showOutput();
-      });
-
+      this._renderWatchedProfile();
     })
   }
 
+  async _resetPartialWatcher(opts) {
+    const { dirs, profilesDir, promises } = this;
+    const Profile = await promises["js"];
+    const partialDirs = Object.values(Profile.partials || {}).map((partialFile) =>
+      path.join(profilesDir, partialFile)
+    );
+
+    dirs["partials"] = partialDirs;
+
+    if (this.partialWatcher) await this.partialWatcher.close();
+    if (!partialDirs.length) {
+      this.partialWatcher = null;
+      return;
+    }
+
+    this.partialWatcher = chokidar.watch(partialDirs, opts).on("change", () => {
+      this._addProfileHandlebarsPromise();
+      this._renderWatchedProfile();
+    });
+  }
+
+  _renderWatchedProfile() {
+    const { command, response, benchmarker } = this;
+
+    benchmarker?.restart(command);
+    return this._createProfile("with-sidebar", ["svg"]).then(() => {
+      benchmarker?.end();
+      response.setTime(benchmarker?.totalTime);
+      response.showOutput();
+    });
+  }
+
   _createProfileOutputName(variant) {
     const {
       settings: {

package/src/cli-commands/GiftExecutor.js

@@ -11,6 +11,7 @@ class GiftExecutor extends Executor {
   constructor(options) {
     super(options);
 
+    this._addHandlebarsPromise();
     this._addTemplatePromise();
     this._addAvatarPromise();
 

package/src/handlebars/importPartials.js

@@ -1,51 +1,17 @@
-const fs = require("fs");
-const { readdir } = require("fs/promises");
+const fs = require("fs/promises");
 const path = require("path");
 
-// These are the profiles that might be used completely in other profiles
-const baseProfiles = [
-  "AMS93",
-  "MMFAD93",
-  "PIES93",
-  "JPFQ93_partial",
-  "JPFQ93_partial2",
-  "FACES93_1_partial",
-  "FACES93_2_1_partial",
-  "FACES93_2_2_partial",
-  "EPQ93",
-  'YPI93_factors'
-];
+const partialsDir = path.join(__dirname, "..", "..", "views", "profiles");
 
-async function importPartials(hbs) {
-  const partialsDir = path.join(__dirname, "..", "..", "views", "profiles");
+async function importPartials(hbs, partials) {
+  await Promise.all(
+    Object.entries(partials).map(async ([name, relativePath]) => {
+      const template = await fs.readFile(path.join(partialsDir, relativePath), "utf-8");
+      hbs.registerPartial(name, template);
+    })
+  );
 
-  let baseProfilePromises = baseProfiles.map((profileName) => {
-    new Promise(function (resolve, reject) {
-      fs.readFile(path.join(partialsDir, "samples", `${profileName}.hbs`), "utf-8", (err, template) => {
-        if (err) reject(err);
-        hbs.registerPartial(profileName, template);
-        resolve(true);
-      });
-    });
-  });
-
-  return readdir(partialsDir).then((partialFiles) => {
-    let generalPartialsPromises = partialFiles.map(
-      (partialFile) =>
-        new Promise(function (resolve, reject) {
-          const matches = /^([^.]+).(hbs|css|js)$/.exec(partialFile);
-          if (!matches) return resolve(true);
-          const name = matches[1];
-          fs.readFile(path.join(partialsDir, partialFile), "utf-8", (err, template) => {
-            if (err) reject(err);
-            hbs.registerPartial(name, template);
-            resolve(true);
-          });
-        })
-    );
-
-    return Promise.all(generalPartialsPromises, baseProfilePromises);
-  });
+  return hbs;
 }
 
 module.exports = importPartials;

package/src/handlebars/init.js

@@ -2,14 +2,20 @@ const Handlebars = require("handlebars");
 const helpers = require("./helpers");
 const importPartials = require("./importPartials");
 
-// Add Custom Helpers to Handlebars
-for (let helper in helpers) Handlebars.registerHelper(helper, helpers[helper]);
-
-module.exports = new Promise(function (resolve, reject) {
-  // Add Partials to Handlebars
-  importPartials(Handlebars)
-    .then(() => resolve(Handlebars))
-    .catch((err) => {
-      reject(err);
-    });
-});
+const sharedPartials = {
+  fonts: "fonts.css",
+  layout: "layout.hbs",
+  sidebar: "sidebar.hbs",
+};
+
+async function createHandlebars(partials = {}) {
+  const hbs = Handlebars.create();
+
+  for (const [name, helper] of Object.entries(helpers)) {
+    hbs.registerHelper(name, helper);
+  }
+
+  return importPartials(hbs, { ...partials, ...sharedPartials });
+}
+
+module.exports = createHandlebars;